From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 09 20:09:43 2010 Received: (at submit) by debbugs.gnu.org; 10 Jul 2010 00:09:43 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXNdX-0000Jb-51 for submit@debbugs.gnu.org; Fri, 09 Jul 2010 20:09:43 -0400 Received: from mx10.gnu.org ([199.232.76.166]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXNdV-0000JW-9m for submit@debbugs.gnu.org; Fri, 09 Jul 2010 20:09:42 -0400 Received: from lists.gnu.org ([199.232.76.165]:52712) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1OXNdR-00031T-Cf for submit@debbugs.gnu.org; Fri, 09 Jul 2010 20:09:37 -0400 Received: from [140.186.70.92] (port=43735 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXNdP-0005ae-9r for bug-gnu-emacs@gnu.org; Fri, 09 Jul 2010 20:09:36 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_NONE autolearn=unavailable version=3.3.1 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OXNbZ-0005ht-5S for bug-gnu-emacs@gnu.org; Fri, 09 Jul 2010 20:07:42 -0400 Received: from mail-gw0-f41.google.com ([74.125.83.41]:47575) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXNbZ-0005hj-1m for bug-gnu-emacs@gnu.org; Fri, 09 Jul 2010 20:07:41 -0400 Received: by gwb1 with SMTP id 1so2010770gwb.0 for ; Fri, 09 Jul 2010 17:07:39 -0700 (PDT) MIME-Version: 1.0 Received: by 10.150.58.20 with SMTP id g20mr2810025yba.84.1278720458984; Fri, 09 Jul 2010 17:07:38 -0700 (PDT) Received: by 10.151.98.19 with HTTP; Fri, 9 Jul 2010 17:07:38 -0700 (PDT) Date: Fri, 9 Jul 2010 20:07:38 -0400 X-Google-Sender-Auth: HlCSPrHLgKoBQEIz8mSgBvFUCHI Message-ID: Subject: Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement. From: MON KEY To: bug-gnu-emacs@gnu.org Content-Type: text/plain; charset=UTF-8 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6, seldom 2.4 (older, 4) X-Spam-Score: -3.8 (---) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 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: -5.1 (-----) Documentation progmodes/grep.el -- numerous errors ommissions and opportunities for improvement. -- There are 13 docstring references of the form: `grep-compute-defaults' in progmodes/grep.el and 7 more in lisp/loaddefs.el including the grep-compute-defaults autoload yet the function itself is not documented. -- The following functions accept a CONFIRM argument: `lgrep', `rgrep', `zrgrep' There is no explicit documentation of the CONFIRM parameter in any of the docstrings for these functions. Likewise, `grep', `lgrep', `rgrep', `grep-find' docs have the following two vacuous statements: "[Cc]ollect output in a buffer." "in the grep output buffer" but do not specify which buffer e.g. the default: "*grep*". -- The constant `grep-expand-keywords' has the typo: "If car of an element matches, the cdr is evalled in to get the" ^ Should probably be: "in order to" Also, the doc makes mention that one should "Note dynamic scoping of variables." but doesn't discuss what these variables are, nor why they should be noted. -- The function `grep-expand-template' uses the term "Patch": "Patch grep COMMAND string replacing , , , , and ." This terminology should be avoided b/c it conflates with diff's `patch'. Likewise, it isn't clear what is getting replaced by the "patch". -- The function `grep-read-files' does not document the REGEXP parameter. -- The variable `grep-find-ignored-directories' should indicate that it defaults to the value of the variable `vc-directory-exclusion-list' as this is an option that is user customizable it may be useful to simply modify the value of that variable instead. -- The variables `grep-template', `grep-find-template', `grep-highlight-matches', `grep-find-command', `grep-use-null-device' say: " {...} to change the default value, use Customize or call the function `grep-apply-setting'." "Customize" should be: "\\[customize]" Likewise, where this is a customizable variable and the intent seems to be that the user _customize_ them the sentence: "You can customize this variable." is already present at the bottom of each of these function's docstrings. -- The variables `grep-template', `grep-find-template' make mention of the `place holders": , , , , saying: "The following place holders should be present in the string:" But do not describe _how_ they should be present. It is not at all clear how these will affect the commands they inform. An example of their usage would be exceedingly beneficial. -- The manual (info "(emacs)Dired and Find") says: "Remember to write the regular expression for `grep', not for Emacs" Its fine if one remembers to do this, but what if it isn't known how to do this in the first place. "Management to Bobby: Okay Bobby, today is your first day at the nuclear power plant... We're sure you'll do fine at your new station. BTW don't forget to secure the Slotin shims before leaving for lunch. You wouldn't wanna end up like poor Louis. Bobby to management: Wait!!! WTF is a Slotin shim... who is Louis? Management to Bobby: Don't worry you'll be fine... Bobby to self (a few hours after returning from lunch - shims forgotten): Must've ate something funny, I think I'm gonna puke." -- /s_P\ From debbugs-submit-bounces@debbugs.gnu.org Fri Oct 11 16:11:07 2019 Received: (at 6598) by debbugs.gnu.org; 11 Oct 2019 20:11:07 +0000 Received: from localhost ([127.0.0.1]:60408 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iJ1Fh-0003XZ-H0 for submit@debbugs.gnu.org; Fri, 11 Oct 2019 16:11:07 -0400 Received: from quimby.gnus.org ([80.91.231.51]:41736) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iJ1Fd-0003X6-Qw for 6598@debbugs.gnu.org; Fri, 11 Oct 2019 16:11:03 -0400 Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=marnie) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iJ1FZ-000230-IY; Fri, 11 Oct 2019 22:11:00 +0200 From: Lars Ingebrigtsen To: MON KEY Subject: Re: bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement. References: Date: Fri, 11 Oct 2019 22:10:57 +0200 In-Reply-To: (MON KEY's message of "Fri, 9 Jul 2010 20:07:38 -0400") Message-ID: <877e5bm4a6.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: MON KEY writes: > Documentation progmodes/grep.el -- numerous errors ommissions and > opportunities for improvement. > > -- > There are 13 docstring references of the form: `grep-compute-defaults' > in progmodes/grep [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 6598 Cc: 6598@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: -1.0 (-) MON KEY writes: > Documentation progmodes/grep.el -- numerous errors ommissions and > opportunities for improvement. > > -- > There are 13 docstring references of the form: `grep-compute-defaults' > in progmodes/grep.el and 7 more in lisp/loaddefs.el including the > grep-compute-defaults autoload yet the function itself is not > documented. OK, added. > -- > The following functions accept a CONFIRM argument: > `lgrep', `rgrep', `zrgrep' > > There is no explicit documentation of the CONFIRM parameter in any of > the docstrings for these functions. Ditto. > Likewise, `grep', `lgrep', `rgrep', `grep-find' docs have the > following two vacuous statements: > > "[Cc]ollect output in a buffer." > "in the grep output buffer" > > but do not specify which buffer e.g. the default: "*grep*". Ditto. > The constant `grep-expand-keywords' has the typo: > > "If car of an element matches, the cdr is evalled in to get the" > ^ > Should probably be: "in order to" > > Also, the doc makes mention that one should > "Note dynamic scoping of variables." > > but doesn't discuss what these variables are, nor why they should be > noted. I've now rephrased it and documented the variables. > -- > The function `grep-expand-template' uses the term "Patch": > > "Patch grep COMMAND string replacing , , , , and ." > > This terminology should be avoided b/c it conflates with diff's `patch'. > Likewise, it isn't clear what is getting replaced by the "patch". I used "expand" instead. > -- > The function `grep-read-files' does not document the REGEXP parameter. Fixed. > The variable `grep-find-ignored-directories' should indicate that it > defaults to the value of the variable `vc-directory-exclusion-list' as > this is an option that is user customizable it may be useful to simply > modify the value of that variable instead. Fixed. > The variables `grep-template', `grep-find-template', > `grep-highlight-matches', `grep-find-command', `grep-use-null-device' > say: > > " {...} to change the default value, use Customize or call the function > `grep-apply-setting'." > > "Customize" should be: "\\[customize]" Fixed. > Likewise, where this is a customizable variable and the intent seems > to be that the user _customize_ them the sentence: > > "You can customize this variable." > > is already present at the bottom of each of these function's > docstrings. I'm guessing the intent here is to say that you can use `grep-apply-setting' instead of Customize, so I think the repetition is OK. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Fri Oct 11 16:14:05 2019 Received: (at control) by debbugs.gnu.org; 11 Oct 2019 20:14:05 +0000 Received: from localhost ([127.0.0.1]:60412 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iJ1Ia-0003cK-P2 for submit@debbugs.gnu.org; Fri, 11 Oct 2019 16:14:05 -0400 Received: from quimby.gnus.org ([80.91.231.51]:41798) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iJ1IY-0003cA-Va for control@debbugs.gnu.org; Fri, 11 Oct 2019 16:14:03 -0400 Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=marnie) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iJ1IV-00023s-NC for control@debbugs.gnu.org; Fri, 11 Oct 2019 22:14:01 +0200 Date: Fri, 11 Oct 2019 22:13:59 +0200 Message-Id: <875zkvm454.fsf@gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #6598 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: tags 6598 fixed close 6598 27.1 quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control 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: -1.0 (-) tags 6598 fixed close 6598 27.1 quit From debbugs-submit-bounces@debbugs.gnu.org Sat Oct 12 02:53:08 2019 Received: (at 6598) by debbugs.gnu.org; 12 Oct 2019 06:53:08 +0000 Received: from localhost ([127.0.0.1]:60640 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iJBH2-0000Pl-9T for submit@debbugs.gnu.org; Sat, 12 Oct 2019 02:53:08 -0400 Received: from eggs.gnu.org ([209.51.188.92]:37653) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iJBH0-0000PL-9I for 6598@debbugs.gnu.org; Sat, 12 Oct 2019 02:53:06 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:33557) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1iJBGu-0005gv-JX; Sat, 12 Oct 2019 02:53:00 -0400 Received: from [176.228.60.248] (port=4057 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1iJBGt-0006sb-UP; Sat, 12 Oct 2019 02:53:00 -0400 Date: Sat, 12 Oct 2019 09:52:50 +0300 Message-Id: <83pnj2o3p9.fsf@gnu.org> From: Eli Zaretskii To: Lars Ingebrigtsen In-reply-to: <877e5bm4a6.fsf@gnus.org> (message from Lars Ingebrigtsen on Fri, 11 Oct 2019 22:10:57 +0200) Subject: Re: bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement. References: <877e5bm4a6.fsf@gnus.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 6598 Cc: 6598@debbugs.gnu.org, monkey@sandpframing.com 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: -3.3 (---) > From: Lars Ingebrigtsen > Date: Fri, 11 Oct 2019 22:10:57 +0200 > Cc: 6598@debbugs.gnu.org > > > The following functions accept a CONFIRM argument: > > `lgrep', `rgrep', `zrgrep' > > > > There is no explicit documentation of the CONFIRM parameter in any of > > the docstrings for these functions. > > Ditto. Thanks, but this: > +If CONFIRM, the user will be given an opportunity to edit the is not our style. Please say "If CONFIRM is non-nil, the user..." instead. (I fixed those in grep.el.) From debbugs-submit-bounces@debbugs.gnu.org Sat Oct 12 13:56:12 2019 Received: (at 6598) by debbugs.gnu.org; 12 Oct 2019 17:56:13 +0000 Received: from localhost ([127.0.0.1]:34102 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iJLci-0001tU-MC for submit@debbugs.gnu.org; Sat, 12 Oct 2019 13:56:12 -0400 Received: from quimby.gnus.org ([80.91.231.51]:36694) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iJLch-0001tO-1V for 6598@debbugs.gnu.org; Sat, 12 Oct 2019 13:56:11 -0400 Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=marnie) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iJLcd-0006TP-MB; Sat, 12 Oct 2019 19:56:10 +0200 From: Lars Ingebrigtsen To: Eli Zaretskii Subject: Re: bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement. References: <877e5bm4a6.fsf@gnus.org> <83pnj2o3p9.fsf@gnu.org> Date: Sat, 12 Oct 2019 19:56:07 +0200 In-Reply-To: <83pnj2o3p9.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 12 Oct 2019 09:52:50 +0300") Message-ID: <87tv8dlufc.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Eli Zaretskii writes: >> +If CONFIRM, the user will be given an opportunity to edit the > > is not our style. Please say "If CONFIRM is non-nil, the user..." > instead. > > (I fixed those in grep.el.) Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 6598 Cc: 6598@debbugs.gnu.org, monkey@sandpframing.com 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: -1.0 (-) Eli Zaretskii writes: >> +If CONFIRM, the user will be given an opportunity to edit the > > is not our style. Please say "If CONFIRM is non-nil, the user..." > instead. > > (I fixed those in grep.el.) Thanks. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From unknown Mon Jun 23 13:09:19 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sun, 10 Nov 2019 12:24:18 +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