bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Michael Heerdegen]

Hi,

the last optional argument of `text-property-search-forward' and
`text-property-search-backward' is named "not-immediate", but the manual
calls it "not-current" (seems since it was added by Lars).  That's all -
please fix the inconsistency.

Thanks,

Michael.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 65 bytes --]

I've fixed it using NOT-CURRENT, which seems marginally clearer.

[-- Attachment #2: Type: text/html, Size: 90 bytes --]

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Michael Heerdegen]

Juanma Barranquero <lekktu@gmail.com> writes:

> I've fixed it using NOT-CURRENT, which seems marginally clearer.

Yes, that's good.  Thanks for fixing.

Michael.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Mon, 23 Sep 2019 09:30:20 +0200
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 37488-done@debbugs.gnu.org
> 
> I've fixed it using NOT-CURRENT, which seems marginally clearer.

Thanks.

I had more problems with these doc strings, so I rewrote them.  Please
take a look.

I have a couple of questions regarding the documentation, which I
couldn't easily figure out.  Please help me understand them and
improve the documentation further:

 . The original doc string said about nil as PREDICATE:

     `nil' means almost the same as \"not equal\", but will also
     end the match if the value of PROPERTY changes.

   What does it mean to "end the match if the value changes"?  The
   text went on to say "See the manual for extensive examples", but
   the manual doesn't mention this aspect of nil, it just says "not
   equal".

 . The doc string stated:

     If NOT-CURRENT, if the match is under point, it will not be
     returned, but instead the next instance is returned, if any.

   But the code, AFAIU, just checks whether the value of PROPERTY at
   point matches that of the found region, which doesn't necessarily
   mean point is part of the region, it could just mean there are two
   regions with matching values of PROPERTY, and point belongs to one
   of them.  Right?

 . What is the reason for having VALUE an optional argument?  Is it a
   frequent/useful operation to look for a VALUE of nil?

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

>  . What is the reason for having VALUE an optional argument?  Is it a
>  frequent/useful operation to look for a VALUE of nil?

I also wondered about the optional args, semantics is a bit unusual:
note that PREDICATE -> nil means "not equal", so with VALUE -> nil this
actually searches for non-nil values of the text property, which is a
reasonable (and the expected) default behavior.  I needed to read it
twice.

Michael.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Juanma Barranquero <lekktu@gmail.com>,  Lars Ingebrigtsen
>  <larsi@gnus.org>,  37488@debbugs.gnu.org
> Date: Wed, 25 Sep 2019 11:35:01 +0200
> 
> note that PREDICATE -> nil means "not equal", so with VALUE -> nil this
> actually searches for non-nil values of the text property, which is a
> reasonable (and the expected) default behavior.

Is it?  IME, we usually search for a specific value, not for any
value.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > note that PREDICATE -> nil means "not equal", so with VALUE -> nil this
> > actually searches for non-nil values of the text property, which is a
> > reasonable (and the expected) default behavior.
>
> Is it?  IME, we usually search for a specific value, not for any
> value.

For me, yes, the function fills a certain gap.  But I'm not an expert on
that matter.

Michael.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: lekktu@gmail.com,  larsi@gnus.org,  37488@debbugs.gnu.org
> Date: Wed, 25 Sep 2019 12:16:30 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > > note that PREDICATE -> nil means "not equal", so with VALUE -> nil this
> > > actually searches for non-nil values of the text property, which is a
> > > reasonable (and the expected) default behavior.
> >
> > Is it?  IME, we usually search for a specific value, not for any
> > value.
> 
> For me, yes, the function fills a certain gap.

Regardless, I think your and my surprise at the default is already a
good sign that the API is sub-optimal.  After all, passing nil as a
mandatory argument is not an issue.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>  . The original doc string said about nil as PREDICATE:
>
>      `nil' means almost the same as \"not equal\", but will also
>      end the match if the value of PROPERTY changes.
>
>    What does it mean to "end the match if the value changes"?  The
>    text went on to say "See the manual for extensive examples", but
>    the manual doesn't mention this aspect of nil, it just says "not
>    equal".

If point is inside a region where PROPERTY has a non-nil value, using
nil as the predicate will end the search when PROPERTY changes value.

>  . The doc string stated:
>
>      If NOT-CURRENT, if the match is under point, it will not be
>      returned, but instead the next instance is returned, if any.
>
>    But the code, AFAIU, just checks whether the value of PROPERTY at
>    point matches that of the found region, which doesn't necessarily
>    mean point is part of the region, it could just mean there are two
>    regions with matching values of PROPERTY, and point belongs to one
>    of them.  Right?

I'm not sure I understand the question...

What it's meant to do is basically how TAB works in buttons, which is a
common use case.  If you're looking for "o", and point is where "|" is
below, then it'll find the last "oo" section after the x-es:

oo|oxxxxxoo

>  . What is the reason for having VALUE an optional argument?  Is it a
>    frequent/useful operation to look for a VALUE of nil?

If PREDICATE is nil, then having to use an explicit nil VALUE isn't
necessary.

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

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Lars Ingebrigtsen]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>> > note that PREDICATE -> nil means "not equal", so with VALUE -> nil this
>> > actually searches for non-nil values of the text property, which is a
>> > reasonable (and the expected) default behavior.
>>
>> Is it?  IME, we usually search for a specific value, not for any
>> value.
>
> For me, yes, the function fills a certain gap.  But I'm not an expert on
> that matter.

In my experience, we almost never search for a specific value for a text
property, but any text that has that property.  That's why I added the
nil PREDICATE to avoid having to supply that awkward lambda into every
function I wrote...

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

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Juanma Barranquero <lekktu@gmail.com>,  37488@debbugs.gnu.org,
>   michael_heerdegen@web.de
> Date: Wed, 25 Sep 2019 15:15:58 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >  . The original doc string said about nil as PREDICATE:
> >
> >      `nil' means almost the same as \"not equal\", but will also
> >      end the match if the value of PROPERTY changes.
> >
> >    What does it mean to "end the match if the value changes"?  The
> >    text went on to say "See the manual for extensive examples", but
> >    the manual doesn't mention this aspect of nil, it just says "not
> >    equal".
> 
> If point is inside a region where PROPERTY has a non-nil value, using
> nil as the predicate will end the search when PROPERTY changes value.

OK, but then it should be obvious, and explicitly mentioning that in
the doc string just makes it more confusing.  Or am I missing
something?

> >  . The doc string stated:
> >
> >      If NOT-CURRENT, if the match is under point, it will not be
> >      returned, but instead the next instance is returned, if any.
> >
> >    But the code, AFAIU, just checks whether the value of PROPERTY at
> >    point matches that of the found region, which doesn't necessarily
> >    mean point is part of the region, it could just mean there are two
> >    regions with matching values of PROPERTY, and point belongs to one
> >    of them.  Right?
> 
> I'm not sure I understand the question...

The code doesn't seem to make sure point is inside the same region as
the one found by the initial attempt, it just compares the values of
PROPERTY at point and in the found region, and if they match, it looks
for another region.  Is that a correct description of what the code
does when NOT-CURRENT is non-nil?

If the description is correct, then the doc string doesn't describe
what the code does accurately.

> What it's meant to do is basically how TAB works in buttons, which is a
> common use case.  If you're looking for "o", and point is where "|" is
> below, then it'll find the last "oo" section after the x-es:
> 
> oo|oxxxxxoo

What does "o" stand for in this case?

> >  . What is the reason for having VALUE an optional argument?  Is it a
> >    frequent/useful operation to look for a VALUE of nil?
> 
> If PREDICATE is nil, then having to use an explicit nil VALUE isn't
> necessary.

I don't understand how this answers my questions.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  lekktu@gmail.com,  37488@debbugs.gnu.org
> Date: Wed, 25 Sep 2019 15:17:11 +0200
> 
> Michael Heerdegen <michael_heerdegen@web.de> writes:
> 
> > Eli Zaretskii <eliz@gnu.org> writes:
> >
> >> > note that PREDICATE -> nil means "not equal", so with VALUE -> nil this
> >> > actually searches for non-nil values of the text property, which is a
> >> > reasonable (and the expected) default behavior.
> >>
> >> Is it?  IME, we usually search for a specific value, not for any
> >> value.
> >
> > For me, yes, the function fills a certain gap.  But I'm not an expert on
> > that matter.
> 
> In my experience, we almost never search for a specific value for a text
> property, but any text that has that property.  That's why I added the
> nil PREDICATE to avoid having to supply that awkward lambda into every
> function I wrote...

We have different experiences, then.

In any case, the API uses double negation in the default case (find
text whose value of PROPERTY does NOT match no-value), which is
baaad...

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> I had more problems with these doc strings, so I rewrote them.  Please
> take a look.

LGTM.

On thing: I'm not sure if it is obvious where a successful
`text-property-search-backward' leaves point - at the beginning or at
the end of the match?

Regards,

Michael.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Juanma Barranquero <lekktu@gmail.com>,  Lars Ingebrigtsen
>  <larsi@gnus.org>,  37488@debbugs.gnu.org
> Date: Thu, 26 Sep 2019 07:55:57 +0200
> 
> On thing: I'm not sure if it is obvious where a successful
> `text-property-search-backward' leaves point - at the beginning or at
> the end of the match?

That was in the original doc strings as well.

I have a couple more questions that didn't yet get answers to my
satisfaction; when that happens, I will try to handle this one as
well.

Thanks.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

Ping!  Please help me finish this job, thanks in advance.

> Date: Wed, 25 Sep 2019 18:01:34 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: michael_heerdegen@web.de, lekktu@gmail.com, 37488@debbugs.gnu.org
> 
> > From: Lars Ingebrigtsen <larsi@gnus.org>
> > Cc: Juanma Barranquero <lekktu@gmail.com>,  37488@debbugs.gnu.org,
> >   michael_heerdegen@web.de
> > Date: Wed, 25 Sep 2019 15:15:58 +0200
> > 
> > Eli Zaretskii <eliz@gnu.org> writes:
> > 
> > >  . The original doc string said about nil as PREDICATE:
> > >
> > >      `nil' means almost the same as \"not equal\", but will also
> > >      end the match if the value of PROPERTY changes.
> > >
> > >    What does it mean to "end the match if the value changes"?  The
> > >    text went on to say "See the manual for extensive examples", but
> > >    the manual doesn't mention this aspect of nil, it just says "not
> > >    equal".
> > 
> > If point is inside a region where PROPERTY has a non-nil value, using
> > nil as the predicate will end the search when PROPERTY changes value.
> 
> OK, but then it should be obvious, and explicitly mentioning that in
> the doc string just makes it more confusing.  Or am I missing
> something?
> 
> > >  . The doc string stated:
> > >
> > >      If NOT-CURRENT, if the match is under point, it will not be
> > >      returned, but instead the next instance is returned, if any.
> > >
> > >    But the code, AFAIU, just checks whether the value of PROPERTY at
> > >    point matches that of the found region, which doesn't necessarily
> > >    mean point is part of the region, it could just mean there are two
> > >    regions with matching values of PROPERTY, and point belongs to one
> > >    of them.  Right?
> > 
> > I'm not sure I understand the question...
> 
> The code doesn't seem to make sure point is inside the same region as
> the one found by the initial attempt, it just compares the values of
> PROPERTY at point and in the found region, and if they match, it looks
> for another region.  Is that a correct description of what the code
> does when NOT-CURRENT is non-nil?
> 
> If the description is correct, then the doc string doesn't describe
> what the code does accurately.
> 
> > What it's meant to do is basically how TAB works in buttons, which is a
> > common use case.  If you're looking for "o", and point is where "|" is
> > below, then it'll find the last "oo" section after the x-es:
> > 
> > oo|oxxxxxoo
> 
> What does "o" stand for in this case?
> 
> > >  . What is the reason for having VALUE an optional argument?  Is it a
> > >    frequent/useful operation to look for a VALUE of nil?
> > 
> > If PREDICATE is nil, then having to use an explicit nil VALUE isn't
> > necessary.
> 
> I don't understand how this answers my questions.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> >  . The original doc string said about nil as PREDICATE:
>> >
>> >      `nil' means almost the same as \"not equal\", but will also
>> >      end the match if the value of PROPERTY changes.
>> >
>> >    What does it mean to "end the match if the value changes"?  The
>> >    text went on to say "See the manual for extensive examples", but
>> >    the manual doesn't mention this aspect of nil, it just says "not
>> >    equal".
>> 
>> If point is inside a region where PROPERTY has a non-nil value, using
>> nil as the predicate will end the search when PROPERTY changes value.
>
> OK, but then it should be obvious, and explicitly mentioning that in
> the doc string just makes it more confusing.  Or am I missing
> something?

It's not obvious -- it's the difference between nil and a lambda that
just says (not (equal...)).

I think the manual needs those copious examples that I apparently forgot
to write.

It's probably easier to understand if you go to a buffer like this:

(defun text-property-setup ()
  (insert "This is "
          (propertize "bold1" 'face 'bold)
          " and this is "
          (propertize "italic1" 'face 'italic)
          (propertize "bold2" 'face 'bold)
          (propertize "italic2" 'face 'italic)
          " at the end")
  (goto-char (point-min)))

and see the difference between 

(text-property-search-forward 'face 'bold nil)

and

(text-property-search-forward 'face 'bold
                              (lambda (val p-val) (not (equal val p-val))))

The latter will stop every time 'face changes, while the former stops in
a way that segments the buffer in all the regions that have not 'face
'bold.

>> >  . The doc string stated:
>> >
>> >      If NOT-CURRENT, if the match is under point, it will not be
>> >      returned, but instead the next instance is returned, if any.
>> >
>> >    But the code, AFAIU, just checks whether the value of PROPERTY at
>> >    point matches that of the found region, which doesn't necessarily
>> >    mean point is part of the region, it could just mean there are two
>> >    regions with matching values of PROPERTY, and point belongs to one
>> >    of them.  Right?
>> 
>> I'm not sure I understand the question...
>
> The code doesn't seem to make sure point is inside the same region as
> the one found by the initial attempt, it just compares the values of
> PROPERTY at point and in the found region, and if they match, it looks
> for another region.  Is that a correct description of what the code
> does when NOT-CURRENT is non-nil?

Yes.

> If the description is correct, then the doc string doesn't describe
> what the code does accurately.

I think that's what the current doc string also says, but perhaps not
clearly enough.

>> What it's meant to do is basically how TAB works in buttons, which is a
>> common use case.  If you're looking for "o", and point is where "|" is
>> below, then it'll find the last "oo" section after the x-es:
>> 
>> oo|oxxxxxoo
>
> What does "o" stand for in this case?

Text with "o" as the property.

>> >  . What is the reason for having VALUE an optional argument?  Is it a
>> >    frequent/useful operation to look for a VALUE of nil?
>> 
>> If PREDICATE is nil, then having to use an explicit nil VALUE isn't
>> necessary.
>
> I don't understand how this answers my questions.

Try (text-property-search-forward 'face) on the example.  It'll give you
all regions that has a face property.

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

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Ping!  Please help me finish this job, thanks in advance.

Hey, that was 23 hours ago.  :-)

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

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> In any case, the API uses double negation in the default case (find
> text whose value of PROPERTY does NOT match no-value), which is
> baaad...

Yes, it was a late addition, not part of the original design,
unfortunately...

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

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: lekktu@gmail.com,  37488@debbugs.gnu.org,  michael_heerdegen@web.de
> Date: Thu, 26 Sep 2019 17:12:46 +0200
> 
> (text-property-search-forward 'face 'bold nil)
> 
> and
> 
> (text-property-search-forward 'face 'bold
>                               (lambda (val p-val) (not (equal val p-val))))
> 
> The latter will stop every time 'face changes, while the former stops in
> a way that segments the buffer in all the regions that have not 'face
> 'bold.

You are saying that the latter will also stop where there's no 'face'
property at all, while the former will only stop where there _is_
'face', but it is not 'bold'?  IOW, nil is equivalent to

  (lambda (val p-val) (and p-val (not (equal val p-val))))

?

> >> >    But the code, AFAIU, just checks whether the value of PROPERTY at
> >> >    point matches that of the found region, which doesn't necessarily
> >> >    mean point is part of the region, it could just mean there are two
> >> >    regions with matching values of PROPERTY, and point belongs to one
> >> >    of them.  Right?
> >> 
> >> I'm not sure I understand the question...
> >
> > The code doesn't seem to make sure point is inside the same region as
> > the one found by the initial attempt, it just compares the values of
> > PROPERTY at point and in the found region, and if they match, it looks
> > for another region.  Is that a correct description of what the code
> > does when NOT-CURRENT is non-nil?
> 
> Yes.
> 
> > If the description is correct, then the doc string doesn't describe
> > what the code does accurately.
> 
> I think that's what the current doc string also says, but perhaps not
> clearly enough.
> 
> >> What it's meant to do is basically how TAB works in buttons, which is a
> >> common use case.  If you're looking for "o", and point is where "|" is
> >> below, then it'll find the last "oo" section after the x-es:
> >> 
> >> oo|oxxxxxoo
> >
> > What does "o" stand for in this case?
> 
> Text with "o" as the property.

But then the code should reject the second "oo" section because the
value of the property there is equal to the value at point.  Right?

> >> >  . What is the reason for having VALUE an optional argument?  Is it a
> >> >    frequent/useful operation to look for a VALUE of nil?
> >> 
> >> If PREDICATE is nil, then having to use an explicit nil VALUE isn't
> >> necessary.
> >
> > I don't understand how this answers my questions.
> 
> Try (text-property-search-forward 'face) on the example.  It'll give you
> all regions that has a face property.

That's a weird way to get to the result, if someone wants it.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> (text-property-search-forward 'face 'bold nil)
>> 
>> and
>> 
>> (text-property-search-forward 'face 'bold
>>                               (lambda (val p-val) (not (equal val p-val))))
>> 
>> The latter will stop every time 'face changes, while the former stops in
>> a way that segments the buffer in all the regions that have not 'face
>> 'bold.
>
> You are saying that the latter will also stop where there's no 'face'
> property at all, while the former will only stop where there _is_
> 'face', but it is not 'bold'?  IOW, nil is equivalent to
>
>   (lambda (val p-val) (and p-val (not (equal val p-val))))

No, not the same, I'm afraid.  nil means "when looping over this search,
give me all regions where 'face is not bold", while your predicate will
give you all regions where there is a 'face property, but it's not nil.

>> >> What it's meant to do is basically how TAB works in buttons, which is a
>> >> common use case.  If you're looking for "o", and point is where "|" is
>> >> below, then it'll find the last "oo" section after the x-es:
>> >> 
>> >> oo|oxxxxxoo
>> >
>> > What does "o" stand for in this case?
>> 
>> Text with "o" as the property.
>
> But then the code should reject the second "oo" section because the
> value of the property there is equal to the value at point.  Right?

Oh, that's the confusion.  By "doesn't include point", I meant "doesn't
include the region point was at when the search started".

>> >> >  . What is the reason for having VALUE an optional argument?  Is it a
>> >> >    frequent/useful operation to look for a VALUE of nil?
>> >> 
>> >> If PREDICATE is nil, then having to use an explicit nil VALUE isn't
>> >> necessary.
>> >
>> > I don't understand how this answers my questions.
>> 
>> Try (text-property-search-forward 'face) on the example.  It'll give you
>> all regions that has a face property.
>
> That's a weird way to get to the result, if someone wants it.

Seems like the obvious way to me.

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

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: michael_heerdegen@web.de,  lekktu@gmail.com,  37488@debbugs.gnu.org
> Date: Thu, 26 Sep 2019 21:16:19 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> (text-property-search-forward 'face 'bold nil)
> >> 
> >> and
> >> 
> >> (text-property-search-forward 'face 'bold
> >>                               (lambda (val p-val) (not (equal val p-val))))
> >> 
> >> The latter will stop every time 'face changes, while the former stops in
> >> a way that segments the buffer in all the regions that have not 'face
> >> 'bold.
> >
> > You are saying that the latter will also stop where there's no 'face'
> > property at all, while the former will only stop where there _is_
> > 'face', but it is not 'bold'?  IOW, nil is equivalent to
> >
> >   (lambda (val p-val) (and p-val (not (equal val p-val))))
> 
> No, not the same, I'm afraid.  nil means "when looping over this search,
> give me all regions where 'face is not bold", while your predicate will
> give you all regions where there is a 'face property, but it's not nil.

OK, the example is bad, but I did get the meaning.

> >> >> What it's meant to do is basically how TAB works in buttons, which is a
> >> >> common use case.  If you're looking for "o", and point is where "|" is
> >> >> below, then it'll find the last "oo" section after the x-es:
> >> >> 
> >> >> oo|oxxxxxoo
> >> >
> >> > What does "o" stand for in this case?
> >> 
> >> Text with "o" as the property.
> >
> > But then the code should reject the second "oo" section because the
> > value of the property there is equal to the value at point.  Right?
> 
> Oh, that's the confusion.  By "doesn't include point", I meant "doesn't
> include the region point was at when the search started".

But that's not what the code seems to do.  It just compares the value
of property in the found region with that at point.  In this example,
they both are "o", so the code will reject the "oo" region at the end,
and try to find the next one (and fail, because there's none).

> >> > I don't understand how this answers my questions.
> >> 
> >> Try (text-property-search-forward 'face) on the example.  It'll give you
> >> all regions that has a face property.
> >
> > That's a weird way to get to the result, if someone wants it.
> 
> Seems like the obvious way to me.

The obvious one would be to call next-single-property-change.

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> But that's not what the code seems to do.  It just compares the value
> of property in the found region with that at point.  In this example,
> they both are "o", so the code will reject the "oo" region at the end,
> and try to find the next one (and fail, because there's none).

No.  Once again, you can test this behaviour with this simple code:

(insert "This is "
         (propertize "bold1" 'face 'bold)
         " and this is "
         (propertize "italic1" 'face 'italic)
         (propertize "bold2" 'face 'bold)
         (propertize "italic2" 'face 'italic)
         " at the end")

Put point inside the first bold text and see the difference between

(text-property-search-forward 'face 'bold t t)

(text-property-search-forward 'face 'bold t nil)

>> >> > I don't understand how this answers my questions.
>> >> 
>> >> Try (text-property-search-forward 'face) on the example.  It'll give you
>> >> all regions that has a face property.
>> >
>> > That's a weird way to get to the result, if someone wants it.
>> 
>> Seems like the obvious way to me.
>
> The obvious one would be to call next-single-property-change.

That doesn't give you the region matched.

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

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: michael_heerdegen@web.de,  lekktu@gmail.com,  37488@debbugs.gnu.org
> Date: Fri, 27 Sep 2019 16:15:47 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > But that's not what the code seems to do.  It just compares the value
> > of property in the found region with that at point.  In this example,
> > they both are "o", so the code will reject the "oo" region at the end,
> > and try to find the next one (and fail, because there's none).
> 
> No.  Once again, you can test this behaviour with this simple code:

Would you please humor me, and explain how the code does that by
walking the code itself?  I have problem understanding that from
examples, sorry for my limitations.

All I see is that the code calls text-property--match-p, and that one
just compares two values of the property.  What am I missing?

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> All I see is that the code calls text-property--match-p, and that one
> just compares two values of the property.  What am I missing?

I think the magic is in text-property--find-end-forward and -backward,
where the nil PREDICATE has special meaning.

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

bug#37488: 27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: michael_heerdegen@web.de,  lekktu@gmail.com,  37488@debbugs.gnu.org
> Date: Fri, 27 Sep 2019 16:36:57 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > All I see is that the code calls text-property--match-p, and that one
> > just compares two values of the property.  What am I missing?
> 
> I think the magic is in text-property--find-end-forward and -backward,
> where the nil PREDICATE has special meaning.

Thanks, I figured it out and updated the doc strings.