bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Lars Ingebrigtsen <larsi@gnus.org>]

Howard Melman <hmelman@gmail.com> writes:

> It's probably impossible to change in the signature because of
> compatibility but perhaps this could inform the docstring.  AIUI if
> this function is not passed a VALUE or PREDICATE it searches for
> regions that contain PROPERTY (a "trick" because a property having a
> nil value is the same as not being present).  But with just a VALUE it
> searches for areas that don't have the PROPERTY/VALUE combo because
> PREDICATE is nil.  And if PREDICATE is t it searches for areas that do
> have that combo.

I think you've gotten how the function works now.  :-)

Except that the nil PREDICATE isn't exactly the same as "not equal" --
in that case, all regions with the same value (that doesn't match) would
be one single match, but the nil PREDICATE also stops when the value
changes.

> Since in lisp a default optional argument is nil, I think the behavior
> with the default value of PREDICATE is reversed from what it should be
> for a function named "search". Particularly since it changes the sense
> of the function from when just PROPERTY is passed as opposed to when
> PROPERTY and VALUE are passed (right?).

The one parameter version is intuitive, while the two parameter version
isn't -- that's true.  And this certainly wasn't helped by the doc
string stating the opposite of how this function worked.  :-)

> Your example of using this function with a while loop definitely helps
> reveal its intended use.  Perhaps including one when passing VALUE to
> the function would help?

I think that's for the manual, which has copious examples and explains
all the bits.  (And has, as far as I can tell, not been corrected to be
wrong while I wasn't looking.  :-))

> I will happily commented on a proposed docstring if you post it here.
> I've not signed papers but do I have to for docstring contributions?

No, that's not necessary -- but is there anything that needs to be
clarified further?

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