* bug#6493: 24.0.50; doc strings of region-beginning, region-end
@ 2010-06-22 16:13 Drew Adams
2010-06-27 12:26 ` bug#6493: Deniz Dogan
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2010-06-22 16:13 UTC (permalink / raw
To: 6493
The doc strings just repeat the function names - they provide no helpful
info at all.
What we need to add is what is said in the Elisp manual: that the
"beginning" ("end") is the position of either point or the mark,
whichever is smaller (larger).
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
of 2010-06-21 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags -Ic:/xpm/include'
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-06-22 16:13 bug#6493: 24.0.50; doc strings of region-beginning, region-end Drew Adams
@ 2010-06-27 12:26 ` Deniz Dogan
2010-06-27 13:52 ` bug#6493: Drew Adams
0 siblings, 1 reply; 26+ messages in thread
From: Deniz Dogan @ 2010-06-27 12:26 UTC (permalink / raw
To: 6493
[-- Attachment #1: Type: text/plain, Size: 38 bytes --]
How about this? (See attached patch.)
[-- Attachment #2: editfns-region-doc.patch --]
[-- Type: application/octet-stream, Size: 794 bytes --]
=== modified file 'src/editfns.c'
--- src/editfns.c 2010-06-16 20:08:41 +0000
+++ src/editfns.c 2010-06-27 12:22:00 +0000
@@ -349,14 +349,18 @@
}
DEFUN ("region-beginning", Fregion_beginning, Sregion_beginning, 0, 0, 0,
- doc: /* Return position of beginning of region, as an integer. */)
+ doc: /* Return position of beginning of region, as an integer.
+
+The beginning of the region is point or mark, whichever is smaller. */)
()
{
return region_limit (1);
}
DEFUN ("region-end", Fregion_end, Sregion_end, 0, 0, 0,
- doc: /* Return position of end of region, as an integer. */)
+ doc: /* Return position of end of region, as an integer.
+
+The end of the region is point or mark, whichever is larger. */)
()
{
return region_limit (0);
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-06-27 12:26 ` bug#6493: Deniz Dogan
@ 2010-06-27 13:52 ` Drew Adams
2010-06-27 14:02 ` bug#6493: Deniz Dogan
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2010-06-27 13:52 UTC (permalink / raw
To: 'Deniz Dogan', 6493
> How about this? (See attached patch.)
1. Thanks for working on this.
2. Please cc the bug submitter, and please put the bug subject line in the
Subject line. It was only by searching old mails for "6493" that I sent that I
was able to find that this was a bug I submitted. Now I must search similarly
for the other bugs you replied to with no Subject line other than the bug #.
Multiply my experience by that of others.
3. What's important about these functions is the return value. The doc string
needs to be explicit about what is _returned_. There is no need to repeat info
that follows from definitions (e.g. that point and mark are the region limits).
Example:
"Returns point or mark, whichever is larger."
Thx.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-06-27 13:52 ` bug#6493: Drew Adams
@ 2010-06-27 14:02 ` Deniz Dogan
2010-06-27 14:18 ` bug#6493: Drew Adams
0 siblings, 1 reply; 26+ messages in thread
From: Deniz Dogan @ 2010-06-27 14:02 UTC (permalink / raw
To: Drew Adams; +Cc: 6493
2010/6/27 Drew Adams <drew.adams@oracle.com>:
>> How about this? (See attached patch.)
>
> 1. Thanks for working on this.
>
> 2. Please cc the bug submitter, and please put the bug subject line in the
> Subject line. It was only by searching old mails for "6493" that I sent that I
> was able to find that this was a bug I submitted. Now I must search similarly
> for the other bugs you replied to with no Subject line other than the bug #.
> Multiply my experience by that of others.
>
Sorry about this, it just wasn't clear to me how people are supposed
to use the bug tracker. I'm not used to accessing bug trackers by
e-mail.
> 3. What's important about these functions is the return value. The doc string
> needs to be explicit about what is _returned_. There is no need to repeat info
> that follows from definitions (e.g. that point and mark are the region limits).
>
> Example:
>
> "Returns point or mark, whichever is larger."
>
How about this (for region-end):
"Returns point or mark, whichever is larger.
The returned value is the position of the end of the region as an integer."
...and likewise for region-beginning.
--
Deniz Dogan
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-06-27 14:02 ` bug#6493: Deniz Dogan
@ 2010-06-27 14:18 ` Drew Adams
2010-06-27 14:29 ` bug#6493: Deniz Dogan
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2010-06-27 14:18 UTC (permalink / raw
To: 'Deniz Dogan'; +Cc: 6493
> > "Returns point or mark, whichever is larger."
>
> How about this (for region-end):
>
> "Returns point or mark, whichever is larger.
> The returned value is the position of the end of the region
> as an integer."
The end of the region is always a position, so no need to speak of the position
of the end of the region.
We don't really need to say that a number is returned, as opposed to a marker.
"Point" is a position, which is a number (natnump). "Mark" is more ambiguous -
it is sometimes referred to as a marker and sometimes as the position of that
marker. So it's probably good to mention that a number is returned, even if not
really necessary. (We also need not specify what kind of number, since it is a
position, but that doesn't hurt either.)
"Returns the larger of point or mark, as a nonnegative integer."
We can add that the function "raises an error if the mark is not set".
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-06-27 14:18 ` bug#6493: Drew Adams
@ 2010-06-27 14:29 ` Deniz Dogan
2010-06-27 14:33 ` bug#6493: Drew Adams
0 siblings, 1 reply; 26+ messages in thread
From: Deniz Dogan @ 2010-06-27 14:29 UTC (permalink / raw
To: Drew Adams; +Cc: 6493
2010/6/27 Drew Adams <drew.adams@oracle.com>:
>> > "Returns point or mark, whichever is larger."
>>
>> How about this (for region-end):
>>
>> "Returns point or mark, whichever is larger.
>> The returned value is the position of the end of the region
>> as an integer."
>
> The end of the region is always a position, so no need to speak of the position
> of the end of the region.
>
> We don't really need to say that a number is returned, as opposed to a marker.
> "Point" is a position, which is a number (natnump). "Mark" is more ambiguous -
> it is sometimes referred to as a marker and sometimes as the position of that
> marker. So it's probably good to mention that a number is returned, even if not
> really necessary. (We also need not specify what kind of number, since it is a
> position, but that doesn't hurt either.)
>
> "Returns the larger of point or mark, as a nonnegative integer."
>
> We can add that the function "raises an error if the mark is not set".
>
>
I'm all for your suggestion. So now we have:
"Returns the larger of point or mark, as a nonnegative integer.
Raises an error if the mark is not set."
Agreed?
--
Deniz Dogan
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-06-27 14:29 ` bug#6493: Deniz Dogan
@ 2010-06-27 14:33 ` Drew Adams
2010-07-10 23:41 ` bug#6493: Deniz Dogan
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2010-06-27 14:33 UTC (permalink / raw
To: 'Deniz Dogan'; +Cc: 6493
> I'm all for your suggestion. So now we have:
> "Returns the larger of point or mark, as a nonnegative integer.
> Raises an error if the mark is not set."
> Agreed?
Yes, thanks.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-06-27 14:33 ` bug#6493: Drew Adams
@ 2010-07-10 23:41 ` Deniz Dogan
2010-07-11 4:20 ` bug#6493: Drew Adams
0 siblings, 1 reply; 26+ messages in thread
From: Deniz Dogan @ 2010-07-10 23:41 UTC (permalink / raw
To: Drew Adams; +Cc: 6493
2010/6/27 Drew Adams <drew.adams@oracle.com>:
>> I'm all for your suggestion. So now we have:
>> "Returns the larger of point or mark, as a nonnegative integer.
>> Raises an error if the mark is not set."
>> Agreed?
>
> Yes, thanks.
>
>
I don't have commit access, Drew. Could you (or anyone else) make this
change now or are we waiting for more comments?
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-10 23:41 ` bug#6493: Deniz Dogan
@ 2010-07-11 4:20 ` Drew Adams
2010-07-23 0:12 ` bug#6493: Juanma Barranquero
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2010-07-11 4:20 UTC (permalink / raw
To: 'Deniz Dogan'; +Cc: 6493
> >> I'm all for your suggestion. So now we have:
> >> "Returns the larger of point or mark, as a nonnegative integer.
> >> Raises an error if the mark is not set."
> >> Agreed?
> >
> > Yes, thanks.
>
> I don't have commit access, Drew. Could you (or anyone else) make this
> change now or are we waiting for more comments?
Someone else will need to help here. I have no idea whether I have commit
access, but I don't know how to commit or otherwise use the version-control
system.
I'm sure that sooner or later some kind soul will commit this. ;-) Thanks for
working on it.
P.S. You might want to ask for commit access for yourself. Dunno what the
process for that is.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-11 4:20 ` bug#6493: Drew Adams
@ 2010-07-23 0:12 ` Juanma Barranquero
2010-07-23 9:10 ` bug#6493: Deniz Dogan
0 siblings, 1 reply; 26+ messages in thread
From: Juanma Barranquero @ 2010-07-23 0:12 UTC (permalink / raw
To: Drew Adams; +Cc: 6493, Deniz Dogan
On Sun, Jul 11, 2010 at 06:20, Drew Adams <drew.adams@oracle.com> wrote:
> I'm sure that sooner or later some kind soul will commit this. ;-) Thanks for
> working on it.
The discussion finished with no updated patch...
Juanma
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-23 0:12 ` bug#6493: Juanma Barranquero
@ 2010-07-23 9:10 ` Deniz Dogan
2010-07-23 9:30 ` bug#6493: Juanma Barranquero
0 siblings, 1 reply; 26+ messages in thread
From: Deniz Dogan @ 2010-07-23 9:10 UTC (permalink / raw
To: Juanma Barranquero; +Cc: 6493
[-- Attachment #1: Type: text/plain, Size: 354 bytes --]
2010/7/23 Juanma Barranquero <lekktu@gmail.com>:
> On Sun, Jul 11, 2010 at 06:20, Drew Adams <drew.adams@oracle.com> wrote:
>
>> I'm sure that sooner or later some kind soul will commit this. ;-) Thanks for
>> working on it.
>
> The discussion finished with no updated patch...
>
> Juanma
>
Attached is a new patch.
--
Deniz Dogan
[-- Attachment #2: editfns-patch-dd.patch --]
[-- Type: application/octet-stream, Size: 768 bytes --]
=== modified file 'src/editfns.c'
--- src/editfns.c 2010-06-16 20:08:41 +0000
+++ src/editfns.c 2010-06-27 12:22:00 +0000
@@ -349,14 +349,18 @@
}
DEFUN ("region-beginning", Fregion_beginning, Sregion_beginning, 0, 0, 0,
- doc: /* Return position of beginning of region, as an integer. */)
+ doc: /* Returns the smaller of point or mark, as a nonnegative integer.
+
+Raises an error if the mark is not set. */)
()
{
return region_limit (1);
}
DEFUN ("region-end", Fregion_end, Sregion_end, 0, 0, 0,
- doc: /* Return position of end of region, as an integer. */)
+ doc: /* Returns the larger of point or mark, as a nonnegative integer.
+
+Raises an error if the mark is not set. */)
()
{
return region_limit (0);
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-23 9:10 ` bug#6493: Deniz Dogan
@ 2010-07-23 9:30 ` Juanma Barranquero
2010-07-23 15:45 ` bug#6493: Chong Yidong
0 siblings, 1 reply; 26+ messages in thread
From: Juanma Barranquero @ 2010-07-23 9:30 UTC (permalink / raw
To: Deniz Dogan; +Cc: 6493
On Fri, Jul 23, 2010 at 11:10, Deniz Dogan <deniz.a.m.dogan@gmail.com> wrote:
> Attached is a new patch.
Thanks.
Three comments:
- You changed "Return" to "Returns", but it is standard Emacs
practice to make the first line in a docstring imperative. From
(elisp) D.6 "Tips for Documentation Strings":
For consistency, phrase the verb in the first sentence of a
function's documentation string as an imperative--for instance,
use "Return the cons of A and B." in preference to "Returns the
cons of A and B."
- You didn't write ChangeLog entries. They are trivial in this case
(so no need to resend), but usually a patch should include them.
- This thead has been just Drew and you, and I'm not sure the result
is better. Though I understand Drew's arguments, it is still a bit
weird to me to look at the docstring of region-(beginning|end) and not
to see *any* reference to the region (yes, I know it is implicit in
"point or mark"). So I'd like to hear more opinions.
Juanma
=== modified file 'src/editfns.c'
--- src/editfns.c 2010-06-16 20:08:41 +0000
+++ src/editfns.c 2010-06-27 12:22:00 +0000
@@ -349,14 +349,18 @@
}
DEFUN ("region-beginning", Fregion_beginning, Sregion_beginning, 0, 0, 0,
- doc: /* Return position of beginning of region, as an integer. */)
+ doc: /* Returns the smaller of point or mark, as a nonnegative integer.
+
+Raises an error if the mark is not set. */)
()
{
return region_limit (1);
}
DEFUN ("region-end", Fregion_end, Sregion_end, 0, 0, 0,
- doc: /* Return position of end of region, as an integer. */)
+ doc: /* Returns the larger of point or mark, as a nonnegative integer.
+
+Raises an error if the mark is not set. */)
()
{
return region_limit (0);
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-23 9:30 ` bug#6493: Juanma Barranquero
@ 2010-07-23 15:45 ` Chong Yidong
2010-07-23 16:16 ` bug#6493: Drew Adams
2010-07-23 17:02 ` bug#6493: Stephen Berman
0 siblings, 2 replies; 26+ messages in thread
From: Chong Yidong @ 2010-07-23 15:45 UTC (permalink / raw
To: Juanma Barranquero; +Cc: 6493, Deniz Dogan
Juanma Barranquero <lekktu@gmail.com> writes:
> On Fri, Jul 23, 2010 at 11:10, Deniz Dogan <deniz.a.m.dogan@gmail.com> wrote:
>
>> Attached is a new patch.
>
> Thanks.
>
> Three comments:
Aside from these points (with which I agree), the addition of "as a
nonnegative integer" is unnecessary. Point and mark are always
non-negative. Also, it is important to keep the word "position",
because mark could otherwise refer to the mark marker. I prefer:
"Return the position of point or mark, whichever is smaller."
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-23 15:45 ` bug#6493: Chong Yidong
@ 2010-07-23 16:16 ` Drew Adams
2010-07-23 17:02 ` bug#6493: Stephen Berman
1 sibling, 0 replies; 26+ messages in thread
From: Drew Adams @ 2010-07-23 16:16 UTC (permalink / raw
To: 'Chong Yidong', 'Juanma Barranquero'
Cc: 6493, 'Deniz Dogan'
> I prefer:
> "Return the position of point or mark, whichever is smaller."
Point _is_ a position. It is the position of the cursor. So that text speaks
about the position of the position of the cursor, which is incorrect.
But you are correct that we do speak of "setting the mark at a position".
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-23 15:45 ` bug#6493: Chong Yidong
2010-07-23 16:16 ` bug#6493: Drew Adams
@ 2010-07-23 17:02 ` Stephen Berman
2010-07-23 17:26 ` bug#6493: Drew Adams
1 sibling, 1 reply; 26+ messages in thread
From: Stephen Berman @ 2010-07-23 17:02 UTC (permalink / raw
To: Chong Yidong; +Cc: Juanma Barranquero, 6493, Deniz Dogan
On Fri, 23 Jul 2010 11:45:13 -0400 Chong Yidong <cyd@stupidchicken.com> wrote:
> Juanma Barranquero <lekktu@gmail.com> writes:
>
>> On Fri, Jul 23, 2010 at 11:10, Deniz Dogan <deniz.a.m.dogan@gmail.com> wrote:
>>
>>> Attached is a new patch.
>>
>> Thanks.
>>
>> Three comments:
>
> Aside from these points (with which I agree), the addition of "as a
> nonnegative integer" is unnecessary. Point and mark are always
> non-negative. Also, it is important to keep the word "position",
> because mark could otherwise refer to the mark marker. I prefer:
>
> "Return the position of point or mark, whichever is smaller."
On Fri, 23 Jul 2010 09:16:48 -0700 "Drew Adams" <drew.adams@oracle.com> wrote:
> Point _is_ a position. It is the position of the cursor. So that text speaks
> about the position of the position of the cursor, which is incorrect.
>
> But you are correct that we do speak of "setting the mark at a position".
How about this:
"Return the smaller of the integer value of point or the mark."
(`value' is used in the doc strings of 'point' and `mark'.)
Steve Berman
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-23 17:02 ` bug#6493: Stephen Berman
@ 2010-07-23 17:26 ` Drew Adams
2010-07-23 17:32 ` bug#6493: Juanma Barranquero
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2010-07-23 17:26 UTC (permalink / raw
To: 'Stephen Berman', 'Chong Yidong'
Cc: 'Juanma Barranquero', 6493, 'Deniz Dogan'
> How about this:
> "Return the smaller of the integer value of point or the mark."
> (`value' is used in the doc strings of 'point' and `mark'.)
The scope of "the integer value of" is ambiguous. Does it apply to "point or
the mark" or to just to "point"? In the latter case, if the mark is smaller
than the integer value of point then the mark is returned. (Yes, a marker can
be compared numerically.)
And in that case, it is incorrect. The mark is a marker. A marker is never
returned here - it is the integer value of the mark (or of point) that is
returned.
And in the former case, the grammar is incorrect - it should be "and" not "or".
It's `min' applied to a plurality (2) of things, not just to one of them. So
"value" needs to be "values" and "or" needs to be "and". Hence:
"Return the smaller of the integer values of point and mark."
But that could conceivably be misread to suggest that either can have multiple
values...
This is what I recommend (very close to what I mentioned in the beginning):
"Return the integer value of point or mark, whichever is smaller."
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-23 17:26 ` bug#6493: Drew Adams
@ 2010-07-23 17:32 ` Juanma Barranquero
2010-07-29 11:44 ` bug#6493: Juanma Barranquero
0 siblings, 1 reply; 26+ messages in thread
From: Juanma Barranquero @ 2010-07-23 17:32 UTC (permalink / raw
To: Drew Adams; +Cc: Chong Yidong, Stephen Berman, 6493, Deniz Dogan
On Fri, Jul 23, 2010 at 19:26, Drew Adams <drew.adams@oracle.com> wrote:
> "Return the integer value of point or mark, whichever is smaller."
FWIW, I like this one.
Juanma
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-23 17:32 ` bug#6493: Juanma Barranquero
@ 2010-07-29 11:44 ` Juanma Barranquero
2010-07-29 15:16 ` bug#6493: Johan Bockgård
2010-07-29 15:58 ` bug#6493: Chong Yidong
0 siblings, 2 replies; 26+ messages in thread
From: Juanma Barranquero @ 2010-07-29 11:44 UTC (permalink / raw
To: Drew Adams; +Cc: Chong Yidong, Stephen Berman, 6493, Deniz Dogan
The conclusion is that Chong thinks that "position" should be kept,
and Drew thinks that it is redundant.
I agree with Drew. The manual says clearly: "The active cursor shows
the location at which editing commands will
take effect, which is called "point"(1)."
So I'd like to commit his proposal ("Return the integer value of point
or mark, whichever is smaller.") and just get rid of this bug.
Juanma
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-29 11:44 ` bug#6493: Juanma Barranquero
@ 2010-07-29 15:16 ` Johan Bockgård
2010-08-01 19:01 ` bug#6493: Juanma Barranquero
2010-07-29 15:58 ` bug#6493: Chong Yidong
1 sibling, 1 reply; 26+ messages in thread
From: Johan Bockgård @ 2010-07-29 15:16 UTC (permalink / raw
To: Juanma Barranquero; +Cc: Chong Yidong, Stephen Berman, 6493, Deniz Dogan
Juanma Barranquero <lekktu@gmail.com> writes:
> So I'd like to commit his proposal ("Return the integer value of point
> or mark, whichever is smaller.") and just get rid of this bug.
Something that should be mentioned in the doc strings is the following:
The next two functions signal an error if the mark does not point
anywhere. If Transient Mark mode is enabled and
`mark-even-if-inactive' is `nil', they also signal an error if the
mark is inactive.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-29 11:44 ` bug#6493: Juanma Barranquero
2010-07-29 15:16 ` bug#6493: Johan Bockgård
@ 2010-07-29 15:58 ` Chong Yidong
1 sibling, 0 replies; 26+ messages in thread
From: Chong Yidong @ 2010-07-29 15:58 UTC (permalink / raw
To: Juanma Barranquero; +Cc: Stephen Berman, 6493, Deniz Dogan
Juanma Barranquero <lekktu@gmail.com> writes:
> The conclusion is that Chong thinks that "position" should be kept,
> and Drew thinks that it is redundant.
>
> I agree with Drew. The manual says clearly: "The active cursor shows
> the location at which editing commands will
> take effect, which is called "point"(1)."
>
> So I'd like to commit his proposal ("Return the integer value of point
> or mark, whichever is smaller.") and just get rid of this bug.
Go ahead.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-07-29 15:16 ` bug#6493: Johan Bockgård
@ 2010-08-01 19:01 ` Juanma Barranquero
2010-08-01 21:17 ` bug#6493: Drew Adams
0 siblings, 1 reply; 26+ messages in thread
From: Juanma Barranquero @ 2010-08-01 19:01 UTC (permalink / raw
To: Johan Bockgård; +Cc: Chong Yidong, Stephen Berman, 6493, Deniz Dogan
On Thu, Jul 29, 2010 at 17:16, Johan Bockgård <bojohan@gnu.org> wrote:
> Something that should be mentioned in the doc strings is the following:
>
> The next two functions signal an error if the mark does not point
> anywhere. If Transient Mark mode is enabled and
> `mark-even-if-inactive' is `nil', they also signal an error if the
> mark is inactive.
Can we simplify that to just say that they signal an error if the
region is not active? (The region-* commands are somewhat specific, so
it's reasonable to suppose that the programmer knows what he's doing
or can lookup the docs.)
Juanma
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-08-01 19:01 ` bug#6493: Juanma Barranquero
@ 2010-08-01 21:17 ` Drew Adams
2010-08-02 3:30 ` bug#6493: Juanma Barranquero
0 siblings, 1 reply; 26+ messages in thread
From: Drew Adams @ 2010-08-01 21:17 UTC (permalink / raw
To: 'Juanma Barranquero', 'Johan Bockgård'
Cc: 'Chong Yidong', 'Stephen Berman', 6493,
'Deniz Dogan'
> > Something that should be mentioned in the doc strings is
> > the following:
> >
> > The next two functions signal an error if the mark does not point
> > anywhere. If Transient Mark mode is enabled and
> > `mark-even-if-inactive' is `nil', they also signal an
> > error if the mark is inactive.
Why should that be mentioned?
What important problem or use case would we be pointing out?
> Can we simplify that to just say that they signal an error if the
> region is not active? (The region-* commands are somewhat specific, so
> it's reasonable to suppose that the programmer knows what he's doing
> or can lookup the docs.)
I have no real objection to a clear statement of the error handling.
In general it is a good idea to mention important error cases.
But I do not think it is necessary to mention error handling at all for these
doc strings. In this case, saying more is saying less, and likely to just add
confusion.
It's pretty obvious that a numerical comparison needs to be done to determine
the smaller/larger of point and mark, and it's similarly obvious that if the
numerical value of one of them (mark) cannot be determined then an error would
be raised.
That does not follow _logically_ - we could return the other value (point is
numeric) or some special value to indicate this condition, but raising an error
seems like common sense and what users would expect. I see no reason to add
info about the error handling.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-08-01 21:17 ` bug#6493: Drew Adams
@ 2010-08-02 3:30 ` Juanma Barranquero
2010-08-02 5:09 ` bug#6493: Drew Adams
2010-08-02 5:34 ` bug#6493: Drew Adams
0 siblings, 2 replies; 26+ messages in thread
From: Juanma Barranquero @ 2010-08-02 3:30 UTC (permalink / raw
To: Drew Adams
Cc: Chong Yidong, Stephen Berman, 6493, Johan Bockgård,
Deniz Dogan
2010/8/1 Drew Adams <drew.adams@oracle.com>:
> That does not follow _logically_ - we could return the other value (point is
> numeric) or some special value to indicate this condition, but raising an error
> seems like common sense and what users would expect.
That's highly subjective IMHO.
Do you oppose to the following (minimal) version?
Juanma
=== modified file 'src/editfns.c'
--- src/editfns.c 2010-07-29 15:50:04 +0000
+++ src/editfns.c 2010-08-02 03:27:32 +0000
@@ -337,5 +337,6 @@
DEFUN ("region-beginning", Fregion_beginning, Sregion_beginning, 0, 0, 0,
- doc: /* Return position of beginning of region, as an integer. */)
+ doc: /* Return the integer value of point or mark, whichever is smaller.
+Signal an error if the region is not active. */)
(void)
{
@@ -344,5 +345,6 @@
DEFUN ("region-end", Fregion_end, Sregion_end, 0, 0, 0,
- doc: /* Return position of end of region, as an integer. */)
+ doc: /* Return the integer value of point or mark, whichever is larger.
+Signal an error if the region is not active. */)
(void)
{
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-08-02 3:30 ` bug#6493: Juanma Barranquero
@ 2010-08-02 5:09 ` Drew Adams
2010-08-02 5:34 ` bug#6493: Drew Adams
1 sibling, 0 replies; 26+ messages in thread
From: Drew Adams @ 2010-08-02 5:09 UTC (permalink / raw
To: 'Juanma Barranquero'
Cc: 'Chong Yidong', 'Stephen Berman', 6493,
'Johan Bockgård', 'Deniz Dogan'
> > an error seems like common sense and what users would expect.
>
> That's highly subjective IMHO.
> Do you oppose to the following (minimal) version?
Nope. (I already said so.)
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-08-02 3:30 ` bug#6493: Juanma Barranquero
2010-08-02 5:09 ` bug#6493: Drew Adams
@ 2010-08-02 5:34 ` Drew Adams
2010-08-02 6:43 ` bug#6493: Juanma Barranquero
1 sibling, 1 reply; 26+ messages in thread
From: Drew Adams @ 2010-08-02 5:34 UTC (permalink / raw
To: 'Juanma Barranquero'
Cc: 'Chong Yidong', 'Stephen Berman', 6493,
'Johan Bockgård', 'Deniz Dogan'
> > > an error seems like common sense and what users would expect.
> >
> > That's highly subjective IMHO.
> > Do you oppose to the following (minimal) version?
>
> Nope. (I already said so.)
Oops, yes, I do oppose it, because it is incorrect.
What I said earlier was:
"I have no real objection to a clear statement of the error handling."
^^^^^^^^^^^^^^^
But it is incorrect that these raise an error if the region is inactive - they
do not.
emacs -Q
Visit some file.
C-SPC, then move point somewhere.
C-g to deactivate the region.
M-: (region-beginning) -> returns the value of `(mark)'.
This is with the default value of `mark-even-if-inactive' and the default of
transient-mark-mode turned on.
If you want to describe the error treatment then you need to do so completely
and correctly. As before, I recommend against describing error handling in this
case, but I do not oppose it if done right.
^ permalink raw reply [flat|nested] 26+ messages in thread
* bug#6493:
2010-08-02 5:34 ` bug#6493: Drew Adams
@ 2010-08-02 6:43 ` Juanma Barranquero
0 siblings, 0 replies; 26+ messages in thread
From: Juanma Barranquero @ 2010-08-02 6:43 UTC (permalink / raw
To: Drew Adams
Cc: Chong Yidong, Stephen Berman, 6493-done, Johan Bockgård,
Deniz Dogan
On Mon, Aug 2, 2010 at 07:34, Drew Adams <drew.adams@oracle.com> wrote:
> Oops, yes, I do oppose it, because it is incorrect.
Committed without the error note.
> If you want to describe the error treatment then you need to do so completely
> and correctly. As before, I recommend against describing error handling in this
> case, but I do not oppose it if done right.
I'l leave that to interested parties.
Juanma
^ permalink raw reply [flat|nested] 26+ messages in thread
end of thread, other threads:[~2010-08-02 6:43 UTC | newest]
Thread overview: 26+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2010-06-22 16:13 bug#6493: 24.0.50; doc strings of region-beginning, region-end Drew Adams
2010-06-27 12:26 ` bug#6493: Deniz Dogan
2010-06-27 13:52 ` bug#6493: Drew Adams
2010-06-27 14:02 ` bug#6493: Deniz Dogan
2010-06-27 14:18 ` bug#6493: Drew Adams
2010-06-27 14:29 ` bug#6493: Deniz Dogan
2010-06-27 14:33 ` bug#6493: Drew Adams
2010-07-10 23:41 ` bug#6493: Deniz Dogan
2010-07-11 4:20 ` bug#6493: Drew Adams
2010-07-23 0:12 ` bug#6493: Juanma Barranquero
2010-07-23 9:10 ` bug#6493: Deniz Dogan
2010-07-23 9:30 ` bug#6493: Juanma Barranquero
2010-07-23 15:45 ` bug#6493: Chong Yidong
2010-07-23 16:16 ` bug#6493: Drew Adams
2010-07-23 17:02 ` bug#6493: Stephen Berman
2010-07-23 17:26 ` bug#6493: Drew Adams
2010-07-23 17:32 ` bug#6493: Juanma Barranquero
2010-07-29 11:44 ` bug#6493: Juanma Barranquero
2010-07-29 15:16 ` bug#6493: Johan Bockgård
2010-08-01 19:01 ` bug#6493: Juanma Barranquero
2010-08-01 21:17 ` bug#6493: Drew Adams
2010-08-02 3:30 ` bug#6493: Juanma Barranquero
2010-08-02 5:09 ` bug#6493: Drew Adams
2010-08-02 5:34 ` bug#6493: Drew Adams
2010-08-02 6:43 ` bug#6493: Juanma Barranquero
2010-07-29 15:58 ` bug#6493: Chong Yidong
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.