From unknown Sat Aug 09 04:52:01 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#23937 <23937@debbugs.gnu.org> To: bug#23937 <23937@debbugs.gnu.org> Subject: Status: 25.0.95; Search functions doc fixes/improvements Reply-To: bug#23937 <23937@debbugs.gnu.org> Date: Sat, 09 Aug 2025 11:52:01 +0000 retitle 23937 25.0.95; Search functions doc fixes/improvements reassign 23937 emacs submitter 23937 Stephen Berman severity 23937 minor thanks From debbugs-submit-bounces@debbugs.gnu.org Sun Jul 10 14:21:57 2016 Received: (at submit) by debbugs.gnu.org; 10 Jul 2016 18:21:57 +0000 Received: from localhost ([127.0.0.1]:45608 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMJMb-0002Ic-2z for submit@debbugs.gnu.org; Sun, 10 Jul 2016 14:21:57 -0400 Received: from eggs.gnu.org ([208.118.235.92]:39723) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMJMZ-0002IP-2H for submit@debbugs.gnu.org; Sun, 10 Jul 2016 14:21:55 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMJMR-0005Tf-Lb for submit@debbugs.gnu.org; Sun, 10 Jul 2016 14:21:49 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,FREEMAIL_FROM autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:58330) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMJMR-0005TN-Hq for submit@debbugs.gnu.org; Sun, 10 Jul 2016 14:21:47 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:58882) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMJMN-0007Re-OI for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:21:46 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMJMI-0005Qu-Kb for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:21:43 -0400 Received: from mout.gmx.net ([212.227.17.20]:54599) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMJMI-0005QD-B7 for bug-gnu-emacs@gnu.org; Sun, 10 Jul 2016 14:21:38 -0400 Received: from rosalinde ([89.245.92.4]) by mail.gmx.com (mrgmx102) with ESMTPSA (Nemesis) id 0MNO33-1bTB7G3Tyr-006tFi for ; Sun, 10 Jul 2016 20:21:36 +0200 From: Stephen Berman To: bug-gnu-emacs@gnu.org Subject: 25.0.95; Search functions doc fixes/improvements Date: Sun, 10 Jul 2016 20:21:34 +0200 Message-ID: <87d1ml8ic1.fsf@gmx.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.95 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:RNklWZGZq4I3Dox7oRVrY7TJN/7mEzIQhAq+jALtpnzIfa8C9H9 oEqyHVhE5vwjyhr3EFnHl0diwubQ1SCjX9X75wzFZnzs0vdMY13Lqz+wWQ2pk+bPpWDl0kb BOvMqnkuO8ETBNT/SSXnrc9/wh+3w13zqdYlpfIfjSs7gUJFMOW3DPHwzD2bYSVApdQUtlR GMynxCV8GeMsReoBDLhRQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:mFWYKeVCAnw=:hTLoQ6x1+a1Ozjur8FbIgL 67EZVB1UFpKm7Y8DbRHfIwCZ7mrVmNanLs7UvETIObeDbFF/B7wURU8dL9uy3I823DwW55VuK 8JVuNRU9QR2PdPJ1h6avVvEBZ7ZLO6HFHwIhsNA2iIZCgnb+58LxfYkZ5h3f69uXMteyJVSPk 9MxRj98NGYYZOeEY/l3pAinIeEPxPlyFIGIbBnqQ0Rniz3ax0QkWBqneEwXeQ4P5PnQDxfUBQ yaD2omOlrpKkh23ks2cDa0OXHwBTgLzWH29OhCqeiH/SLp5ePKgcc73MdgifeKEkQEqU9axRP H5l0ebjKF6TIHkRmKHDkZebRMI37CjYh9GBvb6OpbSlptXVL/WZUiM6SUAquxSj+pTxGnLfGO XG9UJxK7v1hRtiB9x4eK+Kim1PcA1YqXzYSXh0BTYdQ2YvDlNrIgZXFpSLFr78az0rwFwfLvg cTVyQetFtzxU/bdFjpqZz6P3j1unF2xkI/6hbwhWsiL4Ee9rR6C2uQGIZLV0L8M+Rx7mg0PyG k+Ol4BnBFU8+up5hZk8wX21CRvnwhYdS83XuWrhUgZX1tzwkDgq+l2+hajDCmAyPOvkioH7Pz hwNGn9a89L8s2yDT7dGxJKNyA9LX3+moxcDlsNiPxc8V1C24D/vVvrx79HXiTetiv5o712GnM FKpRhN7MUgg2ehfvCejUumZSYJlovbBcpyOn2Q7LT21am5cu22HJL+14w4l2XzRvQtNGRtoZx PYOpvDNO5qApsD1jxiCCnE305IWD1P7gA4r7/KZFPHOonIu3QYqhZcMBCSUooopGjvFISbFW1 soJIv7g X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.1 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.1 (----) 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. 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. diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 1243d72..8d0e4ca 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -44,7 +44,7 @@ String Search buffer is multibyte; they convert the search string to unibyte if the buffer is unibyte. @xref{Text Representations}. -@deffn Command search-forward string &optional limit noerror repeat +@deffn Command search-forward string &optional limit noerror count This function searches forward from point for an exact match for @var{string}. If successful, it sets point to the end of the occurrence found, and returns the new value of point. If no match is found, the @@ -95,24 +95,24 @@ String Search find a match. Invalid arguments cause errors regardless of @var{noerror}. -If @var{repeat} is a positive number @var{n}, it serves as a repeat -count: the search is repeated @var{n} times, each time starting at the -end of the previous time's match. If these successive searches -succeed, the function succeeds, moving point and returning its new -value. Otherwise the search fails, with results depending on the -value of @var{noerror}, as described above. If @var{repeat} is a -negative number -@var{n}, it serves as a repeat count of @var{n} for a -search in the opposite (backward) direction. +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 +match. If all these successive searches succeed, the function call +succeeds, moving point and returning its new value. Otherwise the +function call fails, with results depending on the value of +@var{noerror}, as described above. If @var{count} is a negative +number -@var{n}, the search is done @var{n} times in the opposite +(backward) direction. @end deffn -@deffn Command search-backward string &optional limit noerror repeat +@deffn Command search-backward string &optional limit noerror count This function searches backward from point for @var{string}. It is like @code{search-forward}, except that it searches backwards rather than forwards. Backward searches leave point at the beginning of the match. @end deffn -@deffn Command word-search-forward string &optional limit noerror repeat +@deffn Command word-search-forward string &optional limit noerror count This function searches forward from point for a word match for @var{string}. If it finds a match, it sets point to the end of the match found, and returns the new value of point. @@ -156,8 +156,10 @@ String Search neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the end of the accessible portion of the buffer) and returns @code{nil}. -If @var{repeat} is non-@code{nil}, then the search is repeated that many -times. Point is positioned at the end of the last match. +If @var{count} is a positive number, it specifies how many successive +occurrences to search for. Point is positioned at the end of the last +match. If @var{count} is a negative number, the search is backward +and point is positioned at the beginning of the last match. @findex word-search-regexp Internally, @code{word-search-forward} and related functions use the @@ -165,7 +167,7 @@ String Search regular expression that ignores punctuation. @end deffn -@deffn Command word-search-forward-lax string &optional limit noerror repeat +@deffn Command word-search-forward-lax string &optional limit noerror count This command is identical to @code{word-search-forward}, except that the beginning or the end of @var{string} need not match a word boundary, unless @var{string} begins or ends in whitespace. @@ -173,14 +175,14 @@ String Search but does not match @samp{balls boy}. @end deffn -@deffn Command word-search-backward string &optional limit noerror repeat +@deffn Command word-search-backward string &optional limit noerror count This function searches backward from point for a word match to @var{string}. This function is just like @code{word-search-forward} except that it searches backward and normally leaves point at the beginning of the match. @end deffn -@deffn Command word-search-backward-lax string &optional limit noerror repeat +@deffn Command word-search-backward-lax string &optional limit noerror count This command is identical to @code{word-search-backward}, except that the beginning or the end of @var{string} need not match a word boundary, unless @var{string} begins or ends in whitespace. @@ -1005,7 +1007,7 @@ Regexp Search the buffer is multibyte; they convert the regular expression to unibyte if the buffer is unibyte. @xref{Text Representations}. -@deffn Command re-search-forward regexp &optional limit noerror repeat +@deffn Command re-search-forward regexp &optional limit noerror count This function searches forward in the current buffer for a string of text that is matched by the regular expression @var{regexp}. The function skips over any amount of text that is not matched by @@ -1014,14 +1016,12 @@ Regexp Search If @var{limit} is non-@code{nil}, it must be a position in the current buffer. It specifies the upper bound to the search. No match -extending after that position is accepted. +extending after that position is accepted. If @var{limit} is omitted +or @code{nil}, it defaults to the end of the accessible portion of the +buffer. -If @var{repeat} is supplied, it must be a positive number; the search -is repeated that many times; each repetition starts at the end of the -previous match. If all these successive searches succeed, the search -succeeds, moving point and returning its new value. Otherwise the -search fails. What @code{re-search-forward} does when the search -fails depends on the value of @var{noerror}: +What @code{re-search-forward} does when the search fails depends on +the value of @var{noerror}: @table @asis @item @code{nil} @@ -1033,6 +1033,19 @@ Regexp Search buffer) and return @code{nil}. @end table +The argument @var{noerror} only affects valid searches which fail to +find a match. Invalid arguments cause errors regardless of +@var{noerror}. + +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 +match. If all these successive searches succeed, the function call +succeeds, moving point and returning its new value. Otherwise the +function call fails, with results depending on the value of +@var{noerror}, as described above. If @var{count} is a negative +number -@var{n}, the search is done @var{n} times in the opposite +(backward) direction. + In the following example, point is initially before the @samp{T}. Evaluating the search call moves point to the end of that line (between the @samp{t} of @samp{hat} and the newline). @@ -1057,7 +1070,7 @@ Regexp Search @end example @end deffn -@deffn Command re-search-backward regexp &optional limit noerror repeat +@deffn Command re-search-backward regexp &optional limit noerror count This function searches backward in the current buffer for a string of text that is matched by the regular expression @var{regexp}, leaving point at the beginning of the first text found. @@ -1228,13 +1241,13 @@ POSIX Regexps This is because POSIX backtracking conflicts with the semantics of non-greedy repetition. -@deffn Command posix-search-forward regexp &optional limit noerror repeat +@deffn Command posix-search-forward regexp &optional limit noerror count This is like @code{re-search-forward} except that it performs the full backtracking specified by the POSIX standard for regular expression matching. @end deffn -@deffn Command posix-search-backward regexp &optional limit noerror repeat +@deffn Command posix-search-backward regexp &optional limit noerror count This is like @code{re-search-backward} except that it performs the full backtracking specified by the POSIX standard for regular expression matching. diff --git a/lisp/isearch.el b/lisp/isearch.el index 7360a0b..322f2aa 100644 --- a/lisp/isearch.el +++ b/lisp/isearch.el @@ -1627,7 +1627,8 @@ word-search-backward The match found must not extend before that position. Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument specifies how many successive occurrences to + search for. Relies on the function `word-search-regexp' to convert a sequence of words in STRING to a regexp used to search words without regard @@ -1644,7 +1645,8 @@ word-search-forward The match found must not extend after that position. Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument specifies how many successive occurrences to + search for. Relies on the function `word-search-regexp' to convert a sequence of words in STRING to a regexp used to search words without regard @@ -1665,7 +1667,8 @@ word-search-backward-lax The match found must not extend before that position. Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument specifies how many successive occurrences to + search for. Relies on the function `word-search-regexp' to convert a sequence of words in STRING to a regexp used to search words without regard @@ -1686,7 +1689,8 @@ word-search-forward-lax The match found must not extend after that position. Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument specifies how many successive occurrences to + search for. Relies on the function `word-search-regexp' to convert a sequence of words in STRING to a regexp used to search words without regard diff --git a/src/search.c b/src/search.c index bcdd8f1..6614781 100644 --- a/src/search.c +++ b/src/search.c @@ -2164,7 +2164,8 @@ DEFUN ("search-backward", Fsearch_backward, Ssearch_backward, 1, 4, doc: /* Search backward from point for STRING. Set point to the beginning of the occurrence found, and return point. An optional second argument bounds the search; it is a buffer position. -The match found must not extend before that position. +The match found must not extend before that position. A value of nil is + equivalent to (point-min). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, position at limit of search and return nil. Optional fourth argument COUNT, if non-nil, means to search for COUNT @@ -2204,14 +2205,15 @@ See also the functions `match-beginning', `match-end' and `replace-match'. */) DEFUN ("re-search-backward", Fre_search_backward, Sre_search_backward, 1, 4, "sRE search backward: ", doc: /* Search backward from point for match for regular expression REGEXP. -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. An optional second argument bounds the search; it is a buffer position. -The match found must start at or after that position. +The match found must not extend before that position. A value of nil is + equivalent to (point-min). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument COUNT, if non-nil, means to search for COUNT + successive occurrences. If COUNT is negative, search forward, + instead of backward, for -COUNT occurrences. Search case-sensitivity is determined by the value of the variable `case-fold-search', which see. @@ -2228,10 +2230,13 @@ DEFUN ("re-search-forward", Fre_search_forward, Sre_search_forward, 1, 4, doc: /* Search forward from point for regular expression REGEXP. Set point to the end of the occurrence found, and return point. An optional second argument bounds the search; it is a buffer position. -The match found must not extend after that position. +The match found must not extend after that position. A value of nil is + equivalent to (point-max). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument COUNT, if non-nil, means to search for COUNT + successive occurrences. If COUNT is negative, search backward, + instead of forward, for -COUNT occurrences. Search case-sensitivity is determined by the value of the variable `case-fold-search', which see. @@ -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. An optional second argument bounds the search; it is a buffer position. -The match found must start at or after that position. +The match found must start at or after that position. A value of nil is + equivalent to (point-min). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument COUNT, if non-nil, means to search for COUNT + successive occurrences. If COUNT is negative, search forward, + instead of backward, for -COUNT occurrences. Search case-sensitivity is determined by the value of the variable `case-fold-search', which see. @@ -2272,10 +2278,13 @@ DEFUN ("posix-search-forward", Fposix_search_forward, Sposix_search_forward, 1, Find the longest match in accord with Posix regular expression rules. Set point to the end of the occurrence found, and return point. An optional second argument bounds the search; it is a buffer position. -The match found must not extend after that position. +The match found must not extend after that position. A value of nil is + equivalent to (point-max). Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. -Optional fourth argument is repeat count--search for successive occurrences. +Optional fourth argument COUNT, if non-nil, means to search for COUNT + successive occurrences. If COUNT is negative, search backward, + instead of forward, for -COUNT occurrences. Search case-sensitivity is determined by the value of the variable `case-fold-search', which see. From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 11 11:21:23 2016 Received: (at 23937) by debbugs.gnu.org; 11 Jul 2016 15:21:24 +0000 Received: from localhost ([127.0.0.1]:46998 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMd1P-0004lK-Mi for submit@debbugs.gnu.org; Mon, 11 Jul 2016 11:21:23 -0400 Received: from eggs.gnu.org ([208.118.235.92]:56379) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMd1O-0004l8-E6 for 23937@debbugs.gnu.org; Mon, 11 Jul 2016 11:21:22 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMd1F-0000K9-Az for 23937@debbugs.gnu.org; Mon, 11 Jul 2016 11:21:17 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.5 required=5.0 tests=BAYES_50,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:49021) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMd1F-0000Jr-6x; Mon, 11 Jul 2016 11:21:13 -0400 Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3924 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1bMd1D-00065j-JC; Mon, 11 Jul 2016 11:21:12 -0400 Date: Mon, 11 Jul 2016 18:20:51 +0300 Message-Id: <83lh18cib0.fsf@gnu.org> From: Eli Zaretskii To: Stephen Berman In-reply-to: <87d1ml8ic1.fsf@gmx.net> (message from Stephen Berman on Sun, 10 Jul 2016 20:21:34 +0200) Subject: Re: bug#23937: 25.0.95; Search functions doc fixes/improvements References: <87d1ml8ic1.fsf@gmx.net> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -6.3 (------) X-Debbugs-Envelope-To: 23937 Cc: 23937@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.3 (------) > 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... ;-) > 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. From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 11 17:55:32 2016 Received: (at 23937) by debbugs.gnu.org; 11 Jul 2016 21:55:32 +0000 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 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 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 From: Stephen Berman To: Eli Zaretskii Subject: Re: bug#23937: 25.0.95; Search functions doc fixes/improvements References: <87d1ml8ic1.fsf@gmx.net> <83lh18cib0.fsf@gnu.org> Date: Mon, 11 Jul 2016 23:55:19 +0200 In-Reply-To: <83lh18cib0.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 11 Jul 2016 18:20:51 +0300") Message-ID: <871t2z262g.fsf@gmx.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain 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/eKo2gKBdGUEIoOFp7Zf0hX4TOzgfV7qBNzuKsSU8kwU0Frh0GYwAZi0TPDA9B4hRiVh3O 3pBm5r6 X-Spam-Score: -2.0 (--) X-Debbugs-Envelope-To: 23937 Cc: 23937@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.0 (--) 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 From debbugs-submit-bounces@debbugs.gnu.org Tue Jul 12 01:03:54 2016 Received: (at 23937) by debbugs.gnu.org; 12 Jul 2016 05:03:54 +0000 Received: from localhost ([127.0.0.1]:47444 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMprO-0004A9-7y for submit@debbugs.gnu.org; Tue, 12 Jul 2016 01:03:54 -0400 Received: from eggs.gnu.org ([208.118.235.92]:35478) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMprM-00049r-R2 for 23937@debbugs.gnu.org; Tue, 12 Jul 2016 01:03:53 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMprD-0001S0-Nr for 23937@debbugs.gnu.org; Tue, 12 Jul 2016 01:03:47 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.5 required=5.0 tests=BAYES_50,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:58021) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMprD-0001Rv-Ka; Tue, 12 Jul 2016 01:03:43 -0400 Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4386 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1bMprB-0007JU-Te; Tue, 12 Jul 2016 01:03:42 -0400 Date: Tue, 12 Jul 2016 08:03:25 +0300 Message-Id: <834m7vcusi.fsf@gnu.org> From: Eli Zaretskii To: Stephen Berman In-reply-to: <871t2z262g.fsf@gmx.net> (message from Stephen Berman on Mon, 11 Jul 2016 23:55:19 +0200) Subject: Re: bug#23937: 25.0.95; Search functions doc fixes/improvements References: <87d1ml8ic1.fsf@gmx.net> <83lh18cib0.fsf@gnu.org> <871t2z262g.fsf@gmx.net> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -6.3 (------) X-Debbugs-Envelope-To: 23937 Cc: 23937@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.3 (------) > From: Stephen Berman > Cc: 23937@debbugs.gnu.org > Date: Mon, 11 Jul 2016 23:55:19 +0200 > > >> @@ -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 I don't agree, I think this part is not clear unless explicitly described. I frequently find myself wondering about this when I need to code a loop that uses these functions. > 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) Then let's make it more accurate, but I don't think removing that is TRT. In particular, there's nothing wrong with describing what happens with COUNT = 1 if the clarity is required only in that case. > I assume it's ok to push the changes to emacs-25? Yes. (The comment about COUNT = 0 was a teaser, don't worry about that.) From debbugs-submit-bounces@debbugs.gnu.org Tue Jul 12 08:26:25 2016 Received: (at 23937) by debbugs.gnu.org; 12 Jul 2016 12:26:25 +0000 Received: from localhost ([127.0.0.1]:47704 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMwlc-0001i6-UN for submit@debbugs.gnu.org; Tue, 12 Jul 2016 08:26:25 -0400 Received: from mout.gmx.net ([212.227.15.19]:51547) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMwlZ-0001hs-Mq for 23937@debbugs.gnu.org; Tue, 12 Jul 2016 08:26:23 -0400 Received: from rosalinde ([89.245.68.108]) by mail.gmx.com (mrgmx001) with ESMTPSA (Nemesis) id 0M6zkD-1b8jhb1QQf-00wjgY; Tue, 12 Jul 2016 14:26:14 +0200 From: Stephen Berman To: Eli Zaretskii Subject: Re: bug#23937: 25.0.95; Search functions doc fixes/improvements References: <87d1ml8ic1.fsf@gmx.net> <83lh18cib0.fsf@gnu.org> <871t2z262g.fsf@gmx.net> <834m7vcusi.fsf@gnu.org> Date: Tue, 12 Jul 2016 14:26:12 +0200 In-Reply-To: <834m7vcusi.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 12 Jul 2016 08:03:25 +0300") Message-ID: <87bn239h5n.fsf@rub.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.95 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:K3h9J+Z8np2T38WU+JFm1ejoCD3sF2uo6a/AwpRnjlrCMk0rYai BTIhRcD1QGzNSdioSut9gSviyZAxQLkEwdRDCoHh6yMwqDk/XbK4WUBWOFKS+ZoVdCT7Evi 3MhmVUbwrxcHVrXy7oSHHVk6b30Kx2jrVks67HHklxQJQO59Hm/b3yChygeYJUlDZXaGkQb tksERySHGSb0iM6z9enkQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:qDFg3AiUIdI=:DHbxTzQXTGN2G7P/Y5NUub NtFiXyS6TtV3N6n468yAmVA4QSO9sPsOPO6tOltivY+4aUMTSpvVIBIRI4l9CHKjXD3pZMkd7 ZR437OeirSfGPSxZvTjHx5j8327bYYYP57nc4yDYYVTcE4oV7oX6Y0edC7S3UUrf2Yc0iGYdH CnAxKAnA5cGatA5VH64POe+Rh7vq0cZ2i5VX4vBI4uUgicBNpp7OaVE7nlrutlKIK2n1P2Sty T0K8X4Fp0MBUSHFD9OOSbDbhZvK9vmNvpdsn5DUY5NOtvqnJEs4HhPhchcy3oFVilvDY0Ni7r L13MfGk0tx3qvudyqx/6CC+Su8TSVZSDYNXgRQEM/RLS32CDRukrJff8zq232HLAwthsF2jZN DMcbBd1cI1yWLfdJXoglWVt+kkeuHjXju7jyjMs4GJpcL51sxaoxbHVnnX/Sh6V2J7Udi3IeD WdNx5/FU3yp3xNJwhCQjG9qJvc3jvlTe5+qrMSLG2y0i9ER71FIzzOhX8TF4ey66C/dHdPYm2 KNmmTViUTY+mmEDz6rwNyJuRQknQavvIQvTJBHUta+1mtWoR/YDlSzxL1xfMSAkdDjSohoYmL pENc0GzYn9Kex6EnxPmxZJnL8ukikBuE2/pFlNxSEonhtVb4tv0efU+M6iWRwYvkyPWhvnCil G6SSG4TkmN/ZGyXgneOykATuth4nv7Y0OWG4M8eaVRN0pKROmGF8cEzM48mQ2yyg+brqH2j1d zSwJzDo6Z5v14KRTr/C7jlsEP5/1RaH/nLcXjs8yo9kqjMrCQvCduZnd0s7aQzOdRJHsjGoVH 5YSdPui X-Spam-Score: -2.0 (--) X-Debbugs-Envelope-To: 23937 Cc: 23937@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.0 (--) On Tue, 12 Jul 2016 08:03:25 +0300 Eli Zaretskii wrote: >> From: Stephen Berman >> Cc: 23937@debbugs.gnu.org >> Date: Mon, 11 Jul 2016 23:55:19 +0200 >> >> >> @@ -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 > > I don't agree, I think this part is not clear unless explicitly > described. I frequently find myself wondering about this when I > need to code a loop that uses these functions. > >> 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) > > Then let's make it more accurate, but I don't think removing that is > TRT. In particular, there's nothing wrong with describing what > happens with COUNT = 1 if the clarity is required only in that case. How about the following, which moves the two lines, rephrased for accuracy, to the end of the doc string? Set point to the beginning of the occurrence found, and return point. An optional second argument bounds the search; it is a buffer position. The match found must start at or after that position. A value of nil means search to the beginning of the accessible portion of the buffer. Optional third argument, if t, means if fail just return nil (no error). If not nil and not t, move to limit of search and return nil. 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. The match found is the COUNTth to last one (or last, if COUNT is 1 or nil) in the buffer located entirely before the origin of the search. If you are ok with this, should I add these two lines to all *search-backward and (suitably adapted) *search-forward functions? (The two lines are currently only in {re,posix}-search-backward.) Steve Berman From debbugs-submit-bounces@debbugs.gnu.org Tue Jul 12 09:11:05 2016 Received: (at 23937) by debbugs.gnu.org; 12 Jul 2016 13:11:05 +0000 Received: from localhost ([127.0.0.1]:47741 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMxSn-0002r8-AF for submit@debbugs.gnu.org; Tue, 12 Jul 2016 09:11:05 -0400 Received: from eggs.gnu.org ([208.118.235.92]:58395) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMxSh-0002qj-1T for 23937@debbugs.gnu.org; Tue, 12 Jul 2016 09:10:59 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMxSY-0000bO-7V for 23937@debbugs.gnu.org; Tue, 12 Jul 2016 09:10:49 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.5 required=5.0 tests=BAYES_50,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:35590) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMxSY-0000bC-3q; Tue, 12 Jul 2016 09:10:46 -0400 Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2140 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1bMxSW-0004hF-AN; Tue, 12 Jul 2016 09:10:44 -0400 Date: Tue, 12 Jul 2016 16:10:28 +0300 Message-Id: <83mvlnatob.fsf@gnu.org> From: Eli Zaretskii To: Stephen Berman In-reply-to: <87bn239h5n.fsf@rub.de> (message from Stephen Berman on Tue, 12 Jul 2016 14:26:12 +0200) Subject: Re: bug#23937: 25.0.95; Search functions doc fixes/improvements References: <87d1ml8ic1.fsf@gmx.net> <83lh18cib0.fsf@gnu.org> <871t2z262g.fsf@gmx.net> <834m7vcusi.fsf@gnu.org> <87bn239h5n.fsf@rub.de> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -6.3 (------) X-Debbugs-Envelope-To: 23937 Cc: 23937@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.3 (------) > From: Stephen Berman > Cc: 23937@debbugs.gnu.org > Date: Tue, 12 Jul 2016 14:26:12 +0200 > > Set point to the beginning of the occurrence found, and return point. > An optional second argument bounds the search; it is a buffer position. > The match found must start at or after that position. A value of nil > means search to the beginning of the accessible portion of the buffer. > Optional third argument, if t, means if fail just return nil (no error). > If not nil and not t, move to limit of search and return nil. > 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. > The match found is the COUNTth to last one (or last, if COUNT is 1 or > nil) in the buffer located entirely before the origin of the search. LGTM, thanks. > If you are ok with this, should I add these two lines to all > *search-backward and (suitably adapted) *search-forward functions? (The > two lines are currently only in {re,posix}-search-backward.) It's better for all those doc strings to be consistent, yes. From debbugs-submit-bounces@debbugs.gnu.org Tue Jul 12 11:14:29 2016 Received: (at 23937) by debbugs.gnu.org; 12 Jul 2016 15:14:29 +0000 Received: from localhost ([127.0.0.1]:48491 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMzOH-00067V-BO for submit@debbugs.gnu.org; Tue, 12 Jul 2016 11:14:29 -0400 Received: from mout.gmx.net ([212.227.15.15]:64903) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMzOF-00067I-PA for 23937@debbugs.gnu.org; Tue, 12 Jul 2016 11:14:28 -0400 Received: from rosalinde ([89.245.68.108]) by mail.gmx.com (mrgmx001) with ESMTPSA (Nemesis) id 0LdYdG-1axJcc3dju-00io77; Tue, 12 Jul 2016 17:14:21 +0200 From: Stephen Berman To: Eli Zaretskii Subject: Re: bug#23937: 25.0.95; Search functions doc fixes/improvements References: <87d1ml8ic1.fsf@gmx.net> <83lh18cib0.fsf@gnu.org> <871t2z262g.fsf@gmx.net> <834m7vcusi.fsf@gnu.org> <87bn239h5n.fsf@rub.de> <83mvlnatob.fsf@gnu.org> Date: Tue, 12 Jul 2016 17:14:19 +0200 In-Reply-To: <83mvlnatob.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 12 Jul 2016 16:10:28 +0300") Message-ID: <877fcqanxw.fsf@rub.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.95 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:hqkboHPxicm7L8UjqgrasAjMc1ecOdl6qWELWsZeWlsi5n+QWGW QHKbjDhKdCIfrXMSHVsIOdV7LeepA5qMlTc9rnUknswmlfJaz53o3B8iiiVSIzhLFET8T1l jwsExBIyqZ5ZhKmt6LZE5ahvCDyiI7ObABQzrElUr+P6/fp9NPEJOMuXNPmalPuLQgSHQ6B Dvarx/OxhqqaPRvP/vtUQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:55Xrq/mL8x4=:N40FmyvjS0S+AESUPq0VDR b1iGq2BL7tcEsycxOi5aHzxbS7a3zMujGlirBVQ9QyPgMDb8tHKQjhilw27TeL944cP2LE3Mn 9AN+2qBkAg6PURwYWn/RR8gur8opbdb65spjs3my1WGmVzQ3kmldRfgbL+zRK4Rqm4EZFc2Ex OoHnUJ1rXIeSkci/M7USkUUhbiHV9UrTpEapu0czKsrs92iNFQ8afYxzKYqNaIHf3KuuC3rmL 8mjYjRzYH4xT9q5l/ZQJs1wFuPKB6mWq4BVz9w5alvDzXfJsSrs/ECTfIJMRGFD+xPF9I4mnd UvXILV9LJ41KQAzYkXOxhrz+wxhoOT2B6usrMiYQ8WVkatH5URd2u0ttEks5hwkVPOIiMbkev UY1xXFIcTt6stomUT5U1L9wtBddCGYdOZzrzWLW0iHwAlKW0e8cO32/Y8+CBtDwEz3afemQGR NourunwHOIcqs1DJtcxmlYWFZ73Ydk9OALIBkkHKt7wEkI8kItQPjoOSfc5c4rqArk0HkbLUF KXc7oYF2B64SzCnwUvjnsfjSsOZ5vDQ+yU1fVnj5MGPd84nVkGCKa2Fp1GByOT0QeLYPrTMmj /cipqpvQ7M18IvOIpV3u1bPlGLcqacmPIf79dWIPl5kD95NHMiH86AdiwbpUilU/Hk5T2AjjE oOfpX2dnm2V4A+u8n8jm6Onmib1FVw7kKebpugpfQvi9pgniySMIhiXl+ItKnYaPDKfpx6L9W pfN+r3DihAEx/etofKIjIds9dpF1TxoDEzvXX604lwJl/WrqJKPtJODzDuEH28go8bI3cH/IU HOCtGyB X-Spam-Score: -2.0 (--) X-Debbugs-Envelope-To: 23937 Cc: 23937@debbugs.gnu.org, Stephen Berman X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.0 (--) On Tue, 12 Jul 2016 16:10:28 +0300 Eli Zaretskii wrote: >> From: Stephen Berman >> Cc: 23937@debbugs.gnu.org >> Date: Tue, 12 Jul 2016 14:26:12 +0200 >> >> Set point to the beginning of the occurrence found, and return point. >> An optional second argument bounds the search; it is a buffer position. >> The match found must start at or after that position. A value of nil >> means search to the beginning of the accessible portion of the buffer. >> Optional third argument, if t, means if fail just return nil (no error). >> If not nil and not t, move to limit of search and return nil. >> 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. >> The match found is the COUNTth to last one (or last, if COUNT is 1 or >> nil) in the buffer located entirely before the origin of the search. > > LGTM, thanks. > >> If you are ok with this, should I add these two lines to all >> *search-backward and (suitably adapted) *search-forward functions? (The >> two lines are currently only in {re,posix}-search-backward.) > > It's better for all those doc strings to be consistent, yes. Oh, dear. I made all the changes and was ready to commit them, when I realized that those final two lines are only valid for positive COUNT. Spelling it out for negative COUNT seems like overkill; how about this: With COUNT positive, the match found is the COUNTth to last one (or last, if COUNT is 1 or nil) in the buffer located entirely before the origin of the search; correspondingly with COUNT negative. I hope this is the last point of this issue that needs clarifying. Steve Berman From debbugs-submit-bounces@debbugs.gnu.org Tue Jul 12 11:23:54 2016 Received: (at 23937) by debbugs.gnu.org; 12 Jul 2016 15:23:54 +0000 Received: from localhost ([127.0.0.1]:48501 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMzXO-0006Mp-HA for submit@debbugs.gnu.org; Tue, 12 Jul 2016 11:23:54 -0400 Received: from eggs.gnu.org ([208.118.235.92]:37700) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bMzXM-0006Mc-Px for 23937@debbugs.gnu.org; Tue, 12 Jul 2016 11:23:53 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bMzXD-0004OK-KA for 23937@debbugs.gnu.org; Tue, 12 Jul 2016 11:23:47 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.3 required=5.0 tests=BAYES_20,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:37550) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bMzXD-0004OG-Hb; Tue, 12 Jul 2016 11:23:43 -0400 Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2502 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1bMzXC-0000UO-NQ; Tue, 12 Jul 2016 11:23:43 -0400 Date: Tue, 12 Jul 2016 18:23:26 +0300 Message-Id: <837fcqc235.fsf@gnu.org> From: Eli Zaretskii To: Stephen Berman In-reply-to: <877fcqanxw.fsf@rub.de> (message from Stephen Berman on Tue, 12 Jul 2016 17:14:19 +0200) Subject: Re: bug#23937: 25.0.95; Search functions doc fixes/improvements References: <87d1ml8ic1.fsf@gmx.net> <83lh18cib0.fsf@gnu.org> <871t2z262g.fsf@gmx.net> <834m7vcusi.fsf@gnu.org> <87bn239h5n.fsf@rub.de> <83mvlnatob.fsf@gnu.org> <877fcqanxw.fsf@rub.de> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -6.3 (------) X-Debbugs-Envelope-To: 23937 Cc: 23937@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -6.3 (------) > From: Stephen Berman > Cc: Stephen Berman , 23937@debbugs.gnu.org > Date: Tue, 12 Jul 2016 17:14:19 +0200 > > With COUNT positive, the match found is the COUNTth to last one (or > last, if COUNT is 1 or nil) in the buffer located entirely before > the origin of the search; correspondingly with COUNT negative. OK. From debbugs-submit-bounces@debbugs.gnu.org Tue Jul 12 16:13:49 2016 Received: (at 23937-done) by debbugs.gnu.org; 12 Jul 2016 20:13:49 +0000 Received: from localhost ([127.0.0.1]:48760 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bN43x-0007DL-4m for submit@debbugs.gnu.org; Tue, 12 Jul 2016 16:13:49 -0400 Received: from mout.gmx.net ([212.227.17.22]:50169) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bN43u-0007D6-7q for 23937-done@debbugs.gnu.org; Tue, 12 Jul 2016 16:13:47 -0400 Received: from rosalinde ([89.245.68.108]) by mail.gmx.com (mrgmx102) with ESMTPSA (Nemesis) id 0Mcxtm-1bf8sQ06Xi-00IFIr; Tue, 12 Jul 2016 22:13:40 +0200 From: Stephen Berman To: Eli Zaretskii Subject: Re: bug#23937: 25.0.95; Search functions doc fixes/improvements References: <87d1ml8ic1.fsf@gmx.net> <83lh18cib0.fsf@gnu.org> <871t2z262g.fsf@gmx.net> <834m7vcusi.fsf@gnu.org> <87bn239h5n.fsf@rub.de> <83mvlnatob.fsf@gnu.org> <877fcqanxw.fsf@rub.de> <837fcqc235.fsf@gnu.org> Date: Tue, 12 Jul 2016 22:13:38 +0200 In-Reply-To: <837fcqc235.fsf@gnu.org> (Eli Zaretskii's message of "Tue, 12 Jul 2016 18:23:26 +0300") Message-ID: <8737neaa31.fsf@rub.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.95 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:+nZKiqT9OcdYNcyRhrOqTxRg0Q7mxfgZ2pP/JPasFF8V4siUuzT iwywA3vIGleNNLJysqgr063O7//9HvCJYIRv3uKlf0EAEaV5S7ftn6FjHLtllAXh3941/JT 5+J/84creJSGQrYtBx7yZX9/v2QCc8CyfvcmYk+TeB6qt6OJCugyzBaW8BCZnCAHCTQtz8u Tm3ghqt9xLNql3OvwkhIg== X-UI-Out-Filterresults: notjunk:1;V01:K0:e5dt3dxmxfk=:AfoaigMqhJvIrFQwxnCwx6 sC9gDRQln/BwJlH+3dPdkEmIQdlQp4miNurbEmzdHo+AzsZoVuGmr33n+WQN2GBSMTRvTSfa3 CnicLQ21opddE6WJq1Zh9A7M6tkU237RmvcKeIZs+Bn8mcFyyPPNwFniIw/jheyPhDOQ4Sjm7 LcIWVhULvMorco16fMGb8vvR7e+Bys5lPef8XvPKlf/VbvurPqxa/zQ7j1xldzVLc+NlnYRR5 9/oQs8WGFKPGvCKrDGgiv2IuCqjXJx/fM0dCVXWb/M5M0iGDq0q+ZyQWglkMrXTppOixahn8g 0eWZZlJg87S7w8RqL3bW97888re6PC5Fq1tlkqXkiZvAP6JZopDELa1RIK71/UYmDSWiDFho/ OqZcwuH9hGHc1eYwaTzeAGS8vsgYXQ/qnyAh9EZ9TutOtofvqwFLvem9jkpYdyZ8bP8JTApdT TisR32iYCE/YwZ+t0L/7HHvDXV/exIHZy2uh2ANmn//4Wb4FxjtmNt/KDx2R6K0O4RhYtRfWk r+0KN6FwzoKtnMfrHMYnLazXYrX4w8sajrqYGLGU3JnZVAKKIXUnsWfjJSpJhhxgvyUs/Hs3D HYwrnDTqoIU507QEvZ/QGH3zWE3znFaUZe53T42ub4Imkd7zfQ+eBx2gHX7bsJRWrZ+gpv8Ea PJ8DkWjtzXnEMoYpOsmozjcXBikRJhVaTvtWugVqlE6N8dMl+8HnnltnBchXETAi0L8vdVtIB brct5jFuX5KdkH0SOP/NiBXSTpBUz+KU4CoHMYCkfk52fs93OY16iS9bkBnQnOR4/nuTDT7nk nLhFy2P X-Spam-Score: -2.0 (--) X-Debbugs-Envelope-To: 23937-done Cc: Stephen Berman , 23937-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.0 (--) On Tue, 12 Jul 2016 18:23:26 +0300 Eli Zaretskii wrote: >> From: Stephen Berman >> Cc: Stephen Berman , 23937@debbugs.gnu.org >> Date: Tue, 12 Jul 2016 17:14:19 +0200 >> >> With COUNT positive, the match found is the COUNTth to last one (or >> last, if COUNT is 1 or nil) in the buffer located entirely before >> the origin of the search; correspondingly with COUNT negative. > > OK. Pushed to emacs-25 as commit 069fc05 and closing the bug; thanks for the feedback. Steve Berman From unknown Sat Aug 09 04:52:01 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Thu, 11 Aug 2016 11:24:04 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator