From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stephen Berman Newsgroups: gmane.emacs.bugs Subject: bug#23937: 25.0.95; Search functions doc fixes/improvements Date: Mon, 11 Jul 2016 23:55:19 +0200 Message-ID: <871t2z262g.fsf@gmx.net> References: <87d1ml8ic1.fsf@gmx.net> <83lh18cib0.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1468274191 23363 80.91.229.3 (11 Jul 2016 21:56:31 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 11 Jul 2016 21:56:31 +0000 (UTC) Cc: 23937@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jul 11 23:56:19 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1bMjBZ-0004WV-Lh for geb-bug-gnu-emacs@m.gmane.org; Mon, 11 Jul 2016 23:56:17 +0200 Original-Received: from localhost ([::1]:36179 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMjBY-0006M3-OB for geb-bug-gnu-emacs@m.gmane.org; Mon, 11 Jul 2016 17:56:16 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:51852) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMjBO-0006JR-Dz for bug-gnu-emacs@gnu.org; Mon, 11 Jul 2016 17:56:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMjBK-0000to-70 for bug-gnu-emacs@gnu.org; Mon, 11 Jul 2016 17:56:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:34944) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMjBK-0000tg-3R for bug-gnu-emacs@gnu.org; Mon, 11 Jul 2016 17:56:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1bMjBJ-0006hA-L0 for bug-gnu-emacs@gnu.org; Mon, 11 Jul 2016 17:56:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stephen Berman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 11 Jul 2016 21:56:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 23937 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 23937-submit@debbugs.gnu.org id=B23937.146827413225696 (code B ref 23937); Mon, 11 Jul 2016 21:56:01 +0000 Original-Received: (at 23937) by debbugs.gnu.org; 11 Jul 2016 21:55:32 +0000 Original-Received: from localhost ([127.0.0.1]:47281 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMjAq-0006gO-61 for submit@debbugs.gnu.org; Mon, 11 Jul 2016 17:55:32 -0400 Original-Received: from mout.gmx.net ([212.227.17.20]:63903) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMjAn-0006fz-41 for 23937@debbugs.gnu.org; Mon, 11 Jul 2016 17:55:30 -0400 Original-Received: from rosalinde ([89.245.92.213]) by mail.gmx.com (mrgmx101) with ESMTPSA (Nemesis) id 0MYbFe-1bsACe05kw-00VLd2; Mon, 11 Jul 2016 23:55:22 +0200 In-Reply-To: <83lh18cib0.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 11 Jul 2016 18:20:51 +0300") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) X-Provags-ID: V03:K0:8GQhEhGHKQLK6h0LPgNHlilkMqF9zCuaZzc28elYDj2p9Jpa3H9 G7380B95o2wiF+/w3z5zEURC38wChTX3nm1JHe/73q5POU+Tj5oYvzUEqAN79rfH5v1LucX KIUPii5/wqIGfGwmz8aCgSaTUb1EK7wzAI5l5YvyjKWUQ9QrqhF2s6Dtjujh1R7hjo/Ryfv XWhTTgJ5ShfG3RynuLSgA== X-UI-Out-Filterresults: notjunk:1;V01:K0:DuTiNmgpEEE=:JYUz2w2+uImoZghOrVznBD YAkyxshBiq99gE1C4/jddf1Ge9VHAqSk+lpeH+84xnEeWJJ9Mp0Vsoqccg64eyKXHT8CWeEAT JyMQdc5TTw6MLyZ4GraHjxFLDTVhye5mmid39Pfz7pjsfJsVaiZdhAdjmHCFIoPKebjHHHZ8z LZWogUdBUrfNEsFlntAtfXtv+VEpgYKjANjtkUGrD2Zz2sDXUUVSgw8QZiYcFXHIxLAXmAmG4 fJINL2YyPqNLH0Ceka8UhLJXmlVk96f4qLNVTXH++46Dtxu2cLFh8ilVh/hMTQ8kDTPtdhYho w1fZLk3+CJBV0fwWFMSjxRD/+cIMgzZfzuihBVkxNxw8CQjFHkCqBpMWOxhxAgMCQqpAoZwXJ 1B31xWfo9MdwjW1SY6IcpnMc5sXAaj4FHud+cWAfmgKQs7E49FHRq7fITJ4woMmq3+9ObYUzj Wgl+xmbcMVTnfsi5lZwUfYJkHnTbnUXw7gG1kF9kdmUHjnD2u8vNNxIP2YzQcXpWFwXQWnTIT qoX2Xag1S8B3xD9QGKNUabfW18dRjlb3DKZZdCjaCv1q0P67dFe0y2n7BnAKECEsVFtFkDFDq tFIAIn1P5BgyZ2lUyEbB+WqEWTMJJ+PsCUxTGgVTx31IeWdqy9d8jAl5+rrIOka/c0CiHSOEH /iQSo29GIpXhVlEzyItwr6Wbh1Q2LiW31pcPhD+8JJFHOIK9+IY8zUIPbBjgZLPunsmAm6GSS /YY/eKo2gKBdGUEIoOFp7Zf0hX4TOzgfV7qBNzuKsSU8kwU0Frh0GYwAZi0TPDA9B4hRiVh3 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:120874 Archived-At: On Mon, 11 Jul 2016 18:20:51 +0300 Eli Zaretskii wrote: >> From: Stephen Berman >> 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... ;-) In all seriousness, I actually considered adding that, but then thought it's not really needed, since COUNT means do the search that many times, so doing it zero times means nothing happens, which is exactly the case. (But we could add it, see below.) >> 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. To my understanding, with COUNT > 1 all searches but the initial one are repetitions, but it's fine with me to use "successive search". >> +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? Sure, both of these are fine with me. >> @@ -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? I removed them because I thought they were (i) partly redundant: the first words of the doc string, "Search backward from point", already imply that the match ends before that position, since otherwise it wouldn't be a search backward; and (ii) partly inaccurate: saying the match found is the last one in the buffer before the starting point is only true when COUNT is 1 (or nil). A sufficient and more accurate statement would in effect describe the COUNT argument, which the doc string already does. So I don't see the need for those two lines. But we could add the meaning of nil to the description of COUNT for explicitness, and 0 for completeness (or not, if you think it's not worth it): Optional fourth argument COUNT, if a positive number, means to search for COUNT successive occurrences. If COUNT is negative, search forward, instead of backward, for -COUNT occurrences. A value of nil means the same as 1, and 0 means do nothing. > With those taken care of, LGTM, thanks. Thanks for reviewing. I'll wait for your final decision on the last point, and then I assume it's ok to push the changes to emacs-25? Steve Berman