all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward.
@ 2016-12-13  3:20 Hong Xu
  2016-12-13  6:27 ` Tino Calancha
                   ` (2 more replies)
  0 siblings, 3 replies; 7+ messages in thread
From: Hong Xu @ 2016-12-13  3:20 UTC (permalink / raw)
  To: 25193

	* search.c (Fre_search_forward, Fre_search_backward): Improve doc.
---
 src/search.c | 58 ++++++++++++++++++++++++----------------------------------
 1 file changed, 24 insertions(+), 34 deletions(-)

diff --git a/src/search.c b/src/search.c
index 9f55d728362a..81edc27ecdc8 100644
--- a/src/search.c
+++ b/src/search.c
@@ -2257,26 +2257,12 @@ 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 occurrence found, and return point.
-An optional second argument bounds the search; it is a buffer position.
-  The match found must not begin before 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, position at 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.
-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.
-
-Search case-sensitivity is determined by the value of the variable
-`case-fold-search', which see.
+       doc: /* Search backward from point for regular expression REGEXP.
+This function is almost identical to `re-search-forward', except for
+that by default it searches backward instead of forward, and the sign
+of COUNT also indicates exactly the opposite searching direction.
 
-See also the functions `match-beginning', `match-end', `match-string',
-and `replace-match'.  */)
+See `re-search-forward' for details.  */)
   (Lisp_Object regexp, Lisp_Object bound, Lisp_Object noerror, Lisp_Object count)
 {
   return search_command (regexp, bound, noerror, count, -1, 1, 0);
@@ -2286,21 +2272,25 @@ DEFUN ("re-search-forward", Fre_search_forward, Sre_search_forward, 1, 4,
        "sRE search: ",
        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 end after that position.  A value of nil
-  means search to the end 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
-  backward, instead of forward, for -COUNT occurrences.  A value of
-  nil means the same as 1.
-With COUNT positive, the match found is the COUNTth one (or first,
-  if COUNT is 1 or nil) in the buffer located entirely after the
-  origin of the search; correspondingly with COUNT negative.
-
-Search case-sensitivity is determined by the value of the variable
-`case-fold-search', which see.
+The optional second argument BOUND is a buffer position that bounds
+  the search.  The match found must not end after that position.  A
+  value of nil means search to the end of the accessible portion of
+  the buffer.
+The optional third argument NOERROR indicates how errors are handled
+  when the search fails.  If it is nil or omitted, emit an error; if
+  it is t, simply return nil and do nothing; if it is neither nil nor
+  t, move to the limit of search and return nil.
+The optional fourth argument COUNT is a number that indicates the
+  search direction and the number of occurrences to search for.  If it
+  is positive, search forward for COUNT successive occurrences; if it
+  is negative, search backward, instead of forward, for -COUNT
+  occurrences.  A value of nil means the same as 1.
+With COUNT positive/negative, the match found is the COUNTth/-COUNTth
+  one in the buffer located entirely after/before the origin of the
+  search.
+
+Search case-sensitivity is determined by the variable
+`case-fold-search'.
 
 See also the functions `match-beginning', `match-end', `match-string',
 and `replace-match'.  */)
-- 
2.1.4







^ permalink raw reply related	[flat|nested] 7+ messages in thread

* bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward.
  2016-12-13  3:20 bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward Hong Xu
@ 2016-12-13  6:27 ` Tino Calancha
  2017-04-02  4:42   ` npostavs
  2017-04-02  6:21 ` eliz
  2017-04-14 15:12 ` Nicolas Petton
  2 siblings, 1 reply; 7+ messages in thread
From: Tino Calancha @ 2016-12-13  6:27 UTC (permalink / raw)
  To: Hong Xu; +Cc: 25193, tino.calancha

Hong Xu <hong@topbug.net> writes:

> 	* search.c (Fre_search_forward, Fre_search_backward): Improve doc.
> ---
>  src/search.c | 58 ++++++++++++++++++++++++----------------------------------
>  1 file changed, 24 insertions(+), 34 deletions(-)
>
> diff --git a/src/search.c b/src/search.c
> index 9f55d728362a..81edc27ecdc8 100644
> --- a/src/search.c
> +++ b/src/search.c
> @@ -2257,26 +2257,12 @@ 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 occurrence found, and return point.
> -An optional second argument bounds the search; it is a buffer position.
> -  The match found must not begin before 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, position at 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.
> -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.
> -
> -Search case-sensitivity is determined by the value of the variable
> -`case-fold-search', which see.
> +       doc: /* Search backward from point for regular expression REGEXP.
> +This function is almost identical to `re-search-forward', except for
> +that by default it searches backward instead of forward, and the sign
> +of COUNT also indicates exactly the opposite searching direction.
>  
> -See also the functions `match-beginning', `match-end', `match-string',
> -and `replace-match'.  */)
> +See `re-search-forward' for details.  */)
Thanks for the report.
You could refer for details to the manual, maybe providing a link to the
proper node; but you don't want to refer to the doc string of another
function 'B' to document the arguments of the current function 'A'.
IMO the doc string of 'A' must introduce all its arguments.

Otherwise, i am worry you could go an step further, f.i.
`search-forward'/ `search-backward' share the same optional arguments, so:

1) doc string `re-search-backward': See the doc string of `re-search-forward'
   for details.
2)  doc string `re-search-forward': See the doc string of
   `search-backward' for details.
3)  doc string `search-backward': See the doc string of
   `search-forward' for details.
4)  doc string `search-forward': Wow, you are are very persistent
    user! Please see the manual for details, i am a very busy doc string.

(Reminds me the paperwork in some public agencies).





^ permalink raw reply	[flat|nested] 7+ messages in thread

* bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward.
  2016-12-13  6:27 ` Tino Calancha
@ 2017-04-02  4:42   ` npostavs
  2017-04-02  4:57     ` Tino Calancha
  0 siblings, 1 reply; 7+ messages in thread
From: npostavs @ 2017-04-02  4:42 UTC (permalink / raw)
  To: Tino Calancha; +Cc: Hong Xu, 25193

Tino Calancha <tino.calancha@gmail.com> writes:

> Thanks for the report.
> You could refer for details to the manual, maybe providing a link to the
> proper node; but you don't want to refer to the doc string of another
> function 'B' to document the arguments of the current function 'A'.
> IMO the doc string of 'A' must introduce all its arguments.
>
> Otherwise, i am worry you could go an step further, f.i.
> `search-forward'/ `search-backward' share the same optional arguments, so:

I think it's okay to point to other functions, as long as we keep the
chain to length 1.

> 1) doc string `re-search-backward': See the doc string of `re-search-forward'
>    for details.
> 2)  doc string `re-search-forward': See the doc string of
>    `search-backward' for details.
> 3)  doc string `search-backward': See the doc string of
>    `search-forward' for details.
> 4)  doc string `search-forward': Wow, you are are very persistent
>     user! Please see the manual for details, i am a very busy doc string.

:D

But if all of `re-search-backword', re-search-forward',
`search-backward', would say "see doc string of `search-forward'" I
think it would be okay.





^ permalink raw reply	[flat|nested] 7+ messages in thread

* bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward.
  2017-04-02  4:42   ` npostavs
@ 2017-04-02  4:57     ` Tino Calancha
  0 siblings, 0 replies; 7+ messages in thread
From: Tino Calancha @ 2017-04-02  4:57 UTC (permalink / raw)
  To: npostavs; +Cc: 25193, Tino Calancha, Hong Xu



On Sun, 2 Apr 2017, npostavs@users.sourceforge.net wrote:

> Tino Calancha <tino.calancha@gmail.com> writes:
>
>> Thanks for the report.
>> You could refer for details to the manual, maybe providing a link to the
>> proper node; but you don't want to refer to the doc string of another
>> function 'B' to document the arguments of the current function 'A'.
>> IMO the doc string of 'A' must introduce all its arguments.
>>
>> Otherwise, i am worry you could go an step further, f.i.
>> `search-forward'/ `search-backward' share the same optional arguments, so:
>
> I think it's okay to point to other functions, as long as we keep the
> chain to length 1.
Maybe OK (see below for the rest of my answer, like in my example :)
>> 1) doc string `re-search-backward': See the doc string of `re-search-forward'
>>    for details.
>> 2)  doc string `re-search-forward': See the doc string of
>>    `search-backward' for details.
>> 3)  doc string `search-backward': See the doc string of
>>    `search-forward' for details.
>> 4)  doc string `search-forward': Wow, you are are very persistent
>>     user! Please see the manual for details, i am a very busy doc string.
>
> :D
>
> But if all of `re-search-backword', re-search-forward',
> `search-backward', would say "see doc string of `search-forward'" I
> think it would be okay.
OK for me if it's just 1 jump, but i slightly prefer self-contained
docstrings.  Don't know what Eli or John might think about it.






^ permalink raw reply	[flat|nested] 7+ messages in thread

* bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward.
  2016-12-13  3:20 bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward Hong Xu
  2016-12-13  6:27 ` Tino Calancha
@ 2017-04-02  6:21 ` eliz
  2017-04-06 23:19   ` npostavs
  2017-04-14 15:12 ` Nicolas Petton
  2 siblings, 1 reply; 7+ messages in thread
From: eliz @ 2017-04-02  6:21 UTC (permalink / raw)
  To: Tino Calancha, npostavs; +Cc: 25193, Hong Xu

[-- Attachment #1: Type: text/plain, Size: 803 bytes --]


-------- הודעה מקורית --------מאת: Tino Calancha <tino.calancha@gmail.com> תאריך: 2.4.2017  07:57  (GMT+02:00) אל: npostavs@users.sourceforge.net עותק: 25193@debbugs.gnu.org, Tino Calancha <tino.calancha@gmail.com>, Hong Xu <hong@topbug.net> נושא: bug#25193: [PATCH] Improve the doc of re-search-forward and
 	re-search-backward. 
On Sun, 2 Apr 2017, npostavs@users.sourceforge.net wrote:

>> Tino Calancha <tino.calancha@gmail.com> 
>> :D
>>
>> But if all of `re-search-backword', re-search-forward',
>> `search-backward', would say "see doc string of `search-forward'" I
>> think it would be okay.
>OK for me if it's just 1 jump, but i slightly prefer self-contained
>docstrings.  Don't know what Eli or John might >think about it.


One hop is fine with me, thanks.



[-- Attachment #2: Type: text/html, Size: 1383 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward.
  2017-04-02  6:21 ` eliz
@ 2017-04-06 23:19   ` npostavs
  0 siblings, 0 replies; 7+ messages in thread
From: npostavs @ 2017-04-06 23:19 UTC (permalink / raw)
  To: eliz; +Cc: 25193, Tino Calancha, Hong Xu

tags 25193 fixed
close 25193 25.2
quit

eliz <eliz@gnu.org> writes:

>>>
>>> But if all of `re-search-backword', re-search-forward',
>>> `search-backward', would say "see doc string of `search-forward'" I
>>> think it would be okay.
>>OK for me if it's just 1 jump, but i slightly prefer self-contained
>>docstrings. Don't know what Eli or John might >think about it.
>
> One hop is fine with me, thanks.

Okay, pushed to emacs-25.





^ permalink raw reply	[flat|nested] 7+ messages in thread

* bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward.
  2016-12-13  3:20 bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward Hong Xu
  2016-12-13  6:27 ` Tino Calancha
  2017-04-02  6:21 ` eliz
@ 2017-04-14 15:12 ` Nicolas Petton
  2 siblings, 0 replies; 7+ messages in thread
From: Nicolas Petton @ 2017-04-14 15:12 UTC (permalink / raw)
  To: Hong Xu, 25193

[-- Attachment #1: Type: text/plain, Size: 440 bytes --]

Hong Xu <hong@topbug.net> writes:

Hi Hong,

Thanks for the patch.

> 	* search.c (Fre_search_forward, Fre_search_backward): Improve
> 	doc.

Could you in the future add the path of files in commit messages?
Your commit message would have looked like this:

  * src/search.c (Fre_search_forward, Fre_search_backward): Improve doc.

We use commit messages to generate changelog files, and keep the
etc/AUTHORS file up-to-date.

Cheers,
Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 472 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2017-04-14 15:12 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-12-13  3:20 bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward Hong Xu
2016-12-13  6:27 ` Tino Calancha
2017-04-02  4:42   ` npostavs
2017-04-02  4:57     ` Tino Calancha
2017-04-02  6:21 ` eliz
2017-04-06 23:19   ` npostavs
2017-04-14 15:12 ` Nicolas Petton

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.