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.