bug#31584: 27.0.50; Document again what match re-search-backward finds

[Noam Postavsky]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Michael Heidegger <michael_heerdegen@web.de> writes:
>
>>
>>    (re-search-backward "a*")
>>
>> at the end of a line consisting only "a"s didn't move point.  With
>> today's documentation, that question can't be answered.

The docstring should definitely be clarified, but technically it can
still be answered, if you read very carefully:

    (re-search-backward REGEXP &optional BOUND NOERROR COUNT)

    Search backward from point for regular expression REGEXP.
    This function is almost identical to ‘re-search-forward’, except that
    by default it searches backward instead of forward, and the sign of
    COUNT also indicates exactly the opposite searching direction.

    (re-search-forward REGEXP &optional BOUND NOERROR COUNT)

    [...]
    With COUNT positive/negative, the match found is [...] located
      entirely after/before the origin of the search.

>> Some time ago, we had this sentence in the docstring:
>>
>>    The match found is the one starting last in the buffer
>>    and yet ending before the origin of the search.
>>
>> but it has been removed.  I think we need to say something like that,
>> otherwise the semantics of backward re search is unclear.

Yeah, it is sufficiently surprising that it should be called out
specifically.

> I've been bitten by this before. I'm sure the sentence you cite is,
> correct, but I would suggest something more explicit about backwards
> searches. The most useful thing I could have read when I was wondering
> why this didn't work would be something like: "re-search-backward always
> behaves "non-greedily", i.e., it will find the shortest match before
> point".

It is greedy:

(with-temp-buffer
  (insert "xxxxyyyy")
  (and (re-search-backward "x+y*" nil t)
       (match-string 0))) ;=> "xyyyy"

Non-greedy wouldn't match any "y"s.  It's a bit tricky to explain both
correctly and clearly...