From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Lars Ingebrigtsen Newsgroups: gmane.emacs.bugs Subject: bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement. Date: Fri, 11 Oct 2019 22:10:57 +0200 Message-ID: <877e5bm4a6.fsf@gnus.org> References: Mime-Version: 1.0 Content-Type: text/plain Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="80204"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: 6598@debbugs.gnu.org To: MON KEY Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Oct 11 22:12:25 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iJ1Gy-000Kjo-ET for geb-bug-gnu-emacs@m.gmane.org; Fri, 11 Oct 2019 22:12:24 +0200 Original-Received: from localhost ([::1]:56580 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iJ1Gw-000793-Ag for geb-bug-gnu-emacs@m.gmane.org; Fri, 11 Oct 2019 16:12:22 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:45212) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iJ1Gf-00077i-1i for bug-gnu-emacs@gnu.org; Fri, 11 Oct 2019 16:12:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iJ1Gd-00042w-5q for bug-gnu-emacs@gnu.org; Fri, 11 Oct 2019 16:12:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:51587) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iJ1Gc-00042q-Sz for bug-gnu-emacs@gnu.org; Fri, 11 Oct 2019 16:12:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iJ1Gc-0003Yw-Jj for bug-gnu-emacs@gnu.org; Fri, 11 Oct 2019 16:12:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 11 Oct 2019 20:12:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 6598 X-GNU-PR-Package: emacs Original-Received: via spool by 6598-submit@debbugs.gnu.org id=B6598.157082466713621 (code B ref 6598); Fri, 11 Oct 2019 20:12:02 +0000 Original-Received: (at 6598) by debbugs.gnu.org; 11 Oct 2019 20:11:07 +0000 Original-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 Original-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 Original-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 In-Reply-To: (MON KEY's message of "Fri, 9 Jul 2010 20:07:38 -0400") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:169011 Archived-At: 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