From debbugs-submit-bounces@debbugs.gnu.org Mon Mar 11 12:05:05 2013 Received: (at submit) by debbugs.gnu.org; 11 Mar 2013 16:05:05 +0000 Received: from localhost ([127.0.0.1]:46513 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UF5Dl-0001cq-5f for submit@debbugs.gnu.org; Mon, 11 Mar 2013 12:05:05 -0400 Received: from eggs.gnu.org ([208.118.235.92]:34404) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UF5Di-0001cN-2P for submit@debbugs.gnu.org; Mon, 11 Mar 2013 12:05:03 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UF5Ci-0004uE-OJ for submit@debbugs.gnu.org; Mon, 11 Mar 2013 12:04:01 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-106.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY, USER_IN_WHITELIST autolearn=unavailable version=3.3.2 Received: from lists.gnu.org ([208.118.235.17]:46940) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UF5Ci-0004u9-LP for submit@debbugs.gnu.org; Mon, 11 Mar 2013 12:04:00 -0400 Received: from eggs.gnu.org ([208.118.235.92]:45746) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UF5Cc-0005hD-Dn for bug-gnu-emacs@gnu.org; Mon, 11 Mar 2013 12:04:00 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UF5CX-0004qz-49 for bug-gnu-emacs@gnu.org; Mon, 11 Mar 2013 12:03:54 -0400 Received: from aserp1040.oracle.com ([141.146.126.69]:22837) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UF5CW-0004ql-Ts for bug-gnu-emacs@gnu.org; Mon, 11 Mar 2013 12:03:49 -0400 Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r2BG3kQH011443 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 11 Mar 2013 16:03:47 GMT Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r2BG3jHO027947 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Mon, 11 Mar 2013 16:03:46 GMT Received: from abhmt110.oracle.com (abhmt110.oracle.com [141.146.116.62]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id r2BG3jUs010598 for ; Mon, 11 Mar 2013 11:03:45 -0500 Received: from dradamslap1 (/130.35.178.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 11 Mar 2013 09:03:45 -0700 From: "Drew Adams" To: Subject: 24.3.50; doc strings of Isearch commands Date: Mon, 11 Mar 2013 09:03:44 -0700 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: Ac4ecgHMRDc+Z5wlRuS/SIBxL371lg== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 208.118.235.17 X-Spam-Score: -4.3 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.2 (------) The doc strings of `isearch-forward' etc. should describe each of the arguments. That includes arg NO-RECURSIVE-EDIT. This applies to all Isearch commands. The doc string of `isearch-mode', especially, needs to describe each of its arguments. It currently describes none of them. In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600) of 2013-03-04 on ODIEONE Bzr revision: 111935 yamaoka@jpl.org-20130304102733-4qy111z41qwoh2as Windowing system distributor `Microsoft Corp.', version 5.1.2600 Configured using: `configure --with-gcc (4.7) --no-opt --enable-checking --cflags -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib' From debbugs-submit-bounces@debbugs.gnu.org Mon Apr 29 02:51:21 2013 Received: (at 13923) by debbugs.gnu.org; 29 Apr 2013 06:51:21 +0000 Received: from localhost ([127.0.0.1]:49408 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UWhvf-0008SM-Pk for submit@debbugs.gnu.org; Mon, 29 Apr 2013 02:51:20 -0400 Received: from ps18281.dreamhost.com ([69.163.218.105]:46279 helo=ps18281.dreamhostps.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UWhvT-0008RS-VM for 13923@debbugs.gnu.org; Mon, 29 Apr 2013 02:51:09 -0400 Received: from localhost (ps18281.dreamhostps.com [69.163.218.105]) by ps18281.dreamhostps.com (Postfix) with ESMTP id EF5ED258B9E93C; Sun, 28 Apr 2013 23:50:46 -0700 (PDT) From: Juri Linkov To: "Drew Adams" Subject: Re: bug#13923: 24.3.50; doc strings of Isearch commands Organization: JURTA References: Date: Mon, 29 Apr 2013 09:50:28 +0300 In-Reply-To: (Drew Adams's message of "Mon, 11 Mar 2013 09:03:44 -0700") Message-ID: <87mwshvnp7.fsf@mail.jurta.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: 0.8 (/) X-Debbugs-Envelope-To: 13923 Cc: 13923@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.9 (-) > The doc strings of `isearch-forward' etc. should describe each of the > arguments. That includes arg NO-RECURSIVE-EDIT. This applies to all > Isearch commands. The docstring of `isearch-forward' describes the whole Isearch facility for interactive use with all its available commands and keys. There is only one place to describe `isearch-forward' as a non-interactive function at the end of the docstring that already contains this text: If this function is called non-interactively, it does not return to the calling function until the search is done. that describes the effect of NO-RECURSIVE-EDIT. > The doc string of `isearch-mode', especially, needs to describe each of > its arguments. It currently describes none of them. This is described already in the Commentary section of isearch.el: ;; For programmed use of isearch-mode, e.g. calling (isearch-forward), ;; isearch-mode behaves modally and does not return until the search ;; is completed. It uses a recursive-edit to behave this way. and in the comments of `isearch-mode': ;; isearch-mode can be made modal (in the sense of not returning to ;; the calling function until searching is completed) by entering ;; a recursive-edit and exiting it when done isearching. From debbugs-submit-bounces@debbugs.gnu.org Mon Apr 29 09:42:47 2013 Received: (at 13923) by debbugs.gnu.org; 29 Apr 2013 13:42:47 +0000 Received: from localhost ([127.0.0.1]:49898 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UWoLu-0005Fd-91 for submit@debbugs.gnu.org; Mon, 29 Apr 2013 09:42:47 -0400 Received: from userp1040.oracle.com ([156.151.31.81]:48432) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UWoLn-0005FF-Bq for 13923@debbugs.gnu.org; Mon, 29 Apr 2013 09:42:40 -0400 Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r3TDgJMJ012051 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 29 Apr 2013 13:42:19 GMT Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85]) by ucsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3TDgImd029805 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Mon, 29 Apr 2013 13:42:19 GMT Received: from abhmt115.oracle.com (abhmt115.oracle.com [141.146.116.67]) by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3TDgIqK027998; Mon, 29 Apr 2013 13:42:18 GMT Received: from dradamslap1 (/10.159.75.228) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 29 Apr 2013 06:42:18 -0700 From: "Drew Adams" To: "'Juri Linkov'" References: <87mwshvnp7.fsf@mail.jurta.org> Subject: RE: bug#13923: 24.3.50; doc strings of Isearch commands Date: Mon, 29 Apr 2013 06:42:04 -0700 Message-ID: <9457FCDD57DC456A9526E04663C0009C@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <87mwshvnp7.fsf@mail.jurta.org> Thread-Index: Ac5EpeHdG0ENoYJBS/OqpNp/zQxtXwAOFe9Q X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-Spam-Score: -3.9 (---) X-Debbugs-Envelope-To: 13923 Cc: 13923@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.6 (------) > > The doc strings of `isearch-forward' etc. should describe > > each of the arguments. That includes arg NO-RECURSIVE-EDIT. > > This applies to all Isearch commands. > > The docstring of `isearch-forward' describes the whole > Isearch facility for interactive use with all its available > commands and keys. On its own, irrelevant. If you expect someone looking at the doc string for function `foo' to go to the doc string of function `bar' to get part of `foo's description, then provide a link from foo's doc to bar's, and make clear that the parameters correspond etc. > If this function is called non-interactively, it does not > return to the calling function until the search is done. > > that describes the effect of NO-RECURSIVE-EDIT. Does it say that that is a description of NO-RECURSIVE-EDIT? No. If that is what the intention is, please make the connection, explicitly, so user's do not have to guess that that is what you mean. A user should be able to scan or search the doc string for a parameter name, to find its description (especially when the doc string is long, as in this case). > > The doc string of `isearch-mode', especially, needs to > > describe each of its arguments. It currently describes > > none of them. > > This is described already in the Commentary section of isearch.el: Irrelevant. Which part of "doc string" is not clear? By "self-documenting editor", Emacs does not mean only that you can find some comments that might help in the source code. Emacs promises more than that. From debbugs-submit-bounces@debbugs.gnu.org Tue Apr 30 02:56:20 2013 Received: (at 13923) by debbugs.gnu.org; 30 Apr 2013 06:56:20 +0000 Received: from localhost ([127.0.0.1]:51440 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UX4U7-0005Ej-05 for submit@debbugs.gnu.org; Tue, 30 Apr 2013 02:56:20 -0400 Received: from ps18281.dreamhost.com ([69.163.218.105]:60586 helo=ps18281.dreamhostps.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UX4U5-0005Ec-9g for 13923@debbugs.gnu.org; Tue, 30 Apr 2013 02:56:18 -0400 Received: from localhost (ps18281.dreamhostps.com [69.163.218.105]) by ps18281.dreamhostps.com (Postfix) with ESMTP id 99CC9258B9E91C; Mon, 29 Apr 2013 23:55:54 -0700 (PDT) From: Juri Linkov To: "Drew Adams" Subject: Re: bug#13923: 24.3.50; doc strings of Isearch commands Organization: JURTA References: <87mwshvnp7.fsf@mail.jurta.org> <9457FCDD57DC456A9526E04663C0009C@us.oracle.com> Date: Tue, 30 Apr 2013 09:54:17 +0300 In-Reply-To: <9457FCDD57DC456A9526E04663C0009C@us.oracle.com> (Drew Adams's message of "Mon, 29 Apr 2013 06:42:04 -0700") Message-ID: <87ehdscxuu.fsf@mail.jurta.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -1.9 (-) X-Debbugs-Envelope-To: 13923 Cc: 13923@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.9 (-) > Does it say that that is a description of NO-RECURSIVE-EDIT? No. Thanks for bringing attention to endless omissions in docstrings. > If that is what the intention is, please make the connection, explicitly, so > user's do not have to guess that that is what you mean. Does this patch do what you intended to achieve? === modified file 'lisp/isearch.el' --- lisp/isearch.el 2013-04-27 22:03:42 +0000 +++ lisp/isearch.el 2013-04-30 06:54:05 +0000 @@ -735,8 +735,9 @@ (defun isearch-forward (&optional regexp and are then executed normally (depending on `search-exit-option'). Likewise for function keys and mouse button events. -If this function is called non-interactively, it does not return to -the calling function until the search is done." +If this function is called non-interactively with a nil NO-RECURSIVE-EDIT, +it does not return to the calling function until the search is done. +See the function `isearch-mode' for more information." (interactive "P\np") (isearch-mode t (not (null regexp-p)) nil (not no-recursive-edit))) @@ -799,7 +800,23 @@ (defun isearch-backward-regexp (&optiona (defun isearch-mode (forward &optional regexp op-fun recursive-edit word) "Start Isearch minor mode. -It is called by the function `isearch-forward' and other related functions." +It is called by the function `isearch-forward' and other related functions. + +The non-nil arg FORWARD means searching in the forward direction. + +The non-nil arg REGEXP does an incremental regular expression search. + +The arg OP-FUN is a function to be called after each input character +is processed. (It is not called after characters that exit the search.) + +When the arg RECURSIVE-EDIT is non-nil, this function behaves modally and +does not return to the calling function until the search is completed. +To behave this way it enters a recursive-edit and exits it when done +isearching. + +The arg WORD, if t, does incremental search for a sequence of words, +ignoring punctuation. If the value is a function, it is called to +convert the search string to a regexp used by regexp search functions." ;; Initialize global vars. (setq isearch-forward forward From debbugs-submit-bounces@debbugs.gnu.org Tue Apr 30 09:23:34 2013 Received: (at 13923) by debbugs.gnu.org; 30 Apr 2013 13:23:34 +0000 Received: from localhost ([127.0.0.1]:51795 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UXAWq-0005Cv-Jr for submit@debbugs.gnu.org; Tue, 30 Apr 2013 09:23:34 -0400 Received: from aserp1040.oracle.com ([141.146.126.69]:46642) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UXAWo-0005Cc-15 for 13923@debbugs.gnu.org; Tue, 30 Apr 2013 09:23:31 -0400 Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r3UDN4gZ028762 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 30 Apr 2013 13:23:05 GMT Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3UDN3Ht016794 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Tue, 30 Apr 2013 13:23:04 GMT Received: from abhmt118.oracle.com (abhmt118.oracle.com [141.146.116.70]) by userz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3UDN383025576; Tue, 30 Apr 2013 13:23:03 GMT Received: from dradamslap1 (/10.159.236.42) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 30 Apr 2013 06:23:03 -0700 From: "Drew Adams" To: "'Juri Linkov'" References: <87mwshvnp7.fsf@mail.jurta.org><9457FCDD57DC456A9526E04663C0009C@us.oracle.com> <87ehdscxuu.fsf@mail.jurta.org> Subject: RE: bug#13923: 24.3.50; doc strings of Isearch commands Date: Tue, 30 Apr 2013 06:22:58 -0700 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: Ac5Fb8NDdxbsu/4ZT8WkwO3Ctib2UQANdl1g X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 In-Reply-To: <87ehdscxuu.fsf@mail.jurta.org> X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Spam-Score: -4.8 (----) X-Debbugs-Envelope-To: 13923 Cc: 13923@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.7 (------) > > Does it say that that is a description of NO-RECURSIVE-EDIT? No. > > Thanks for bringing attention to endless omissions in docstrings. > > > If that is what the intention is, please make the connection, > > explicitly, so user's do not have to guess that that > > is what you mean. > > Does this patch do what you intended to achieve? Yes, it is an improvement. Thanks. From debbugs-submit-bounces@debbugs.gnu.org Wed May 01 04:13:07 2013 Received: (at control) by debbugs.gnu.org; 1 May 2013 08:13:07 +0000 Received: from localhost ([127.0.0.1]:53264 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UXS9y-0003us-9c for submit@debbugs.gnu.org; Wed, 01 May 2013 04:13:07 -0400 Received: from ps18281.dreamhost.com ([69.163.218.105]:54284 helo=ps18281.dreamhostps.com) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UXS9w-0003ua-7q for control@debbugs.gnu.org; Wed, 01 May 2013 04:13:04 -0400 Received: from localhost (ps18281.dreamhostps.com [69.163.218.105]) by ps18281.dreamhostps.com (Postfix) with ESMTP id 6E9AD258B92943 for ; Wed, 1 May 2013 01:12:35 -0700 (PDT) From: Juri Linkov To: control@debbugs.gnu.org Subject: Re: bug#13923: 24.3.50; doc strings of Isearch commands Organization: JURTA References: <87mwshvnp7.fsf@mail.jurta.org> <9457FCDD57DC456A9526E04663C0009C@us.oracle.com> <87ehdscxuu.fsf@mail.jurta.org> Date: Wed, 01 May 2013 11:10:40 +0300 In-Reply-To: (Drew Adams's message of "Tue, 30 Apr 2013 06:22:58 -0700") Message-ID: <874nenrugu.fsf@mail.jurta.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (x86_64-pc-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: 0.8 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.9 (-) close 13923 stop From unknown Sat Aug 16 21:16:50 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Wed, 29 May 2013 11:24:03 +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