bug#23937: 25.0.95; Search functions doc fixes/improvements

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Date: Sun, 10 Jul 2016 20:21:34 +0200
> 
> In GNU Emacs 25.0.95.9 (x86_64-suse-linux-gnu, GTK+ Version 3.14.15)
>  of 2016-07-10 built on rosalinde
> Repository revision: 4069b716ad3422f2d7f595699220c39297427387
> 
> Bug#10507 was about missing documentation for the fact that the fourth
> argument of search-{for,back}ward can be a negative number, reversing
> the search direction.  This lack was fixed in commit acc28cb, but that
> commit didn't correspondingly augment the doc of the other search
> functions (word-search-*, re-search-*, posix-search-*), which have the
> same behavior.

(But no one has documented what happens if COUNT is zero... ;-)

> The patch below does this.  In addition, the
> documentation in the Lisp reference uses the word "repeat" instead of
> "count" for that argument, and says the search is repeated N times,
> where N is the argument's value; but strictly speaking, it's repeated
> N-1 times.  It may be clear what's intended, but there's no need for the
> manual to differ from (and be strictly less accurate than) the doc
> strings on this point, so the patch changes the manual accordingly.
> Finally, the patch also adds the information about the nil value of the
> bound/limit argument to those doc strings/manual entries where it's
> missing.  In short the patch makes the doc of all these functions more
> uniform.

Thanks.  I have some minor comments.

> +If @var{count} is a positive number @var{n}, the search is done
> +@var{n} times; each repetition starts at the end of the previous
                       ^^^^^^^^^^
With the change in the name of the argument, there's no more
"repetitions".  Suggest to use "successive search" instead.

> +If @var{count} is a positive number @var{n}, the search is done
> +@var{n} times; each repetition starts at the end of the previous
                       ^^^^^^^^^^
Likewise.

> +The match found must not extend before that position.  A value of nil is
> +  equivalent to (point-min).

I find references to point-min and point-max in doc strings not the
best style.  I think saying "the search is unlimited" or "defaults to
the beginning of the buffer's accessible region" is more
user-friendly.

Btw, since this is search backwards, the "extend" part might be
confusing; perhaps it is better to say "match must not begin before
that position" instead?

> @@ -2247,14 +2252,15 @@ DEFUN ("posix-search-backward", 
> Fposix_search_backward, Sposix_search_backward,
>         "sPosix search backward: ",
>         doc: /* Search backward from point for match for regular expression 
> REGEXP.
>  Find the longest match in accord with Posix regular expression rules.
> -Set point to the beginning of the match, and return point.
> -The match found is the one starting last in the buffer
> -and yet ending before the origin of the search.
> +Set point to the beginning of the occurrence found, and return point.

The 2nd and 3rd lines you removed seem to provide valuable information
which is now gone, no?

With those taken care of, LGTM, thanks.