From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: MON KEY Newsgroups: gmane.emacs.bugs Subject: bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement. Date: Fri, 9 Jul 2010 20:07:38 -0400 Message-ID: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: dough.gmane.org 1278721820 6987 80.91.229.12 (10 Jul 2010 00:30:20 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 10 Jul 2010 00:30:20 +0000 (UTC) To: 6598@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jul 10 02:30:17 2010 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1OXNxM-0003rl-7o for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Jul 2010 02:30:12 +0200 Original-Received: from localhost ([127.0.0.1]:35047 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXNxL-0002ST-LP for geb-bug-gnu-emacs@m.gmane.org; Fri, 09 Jul 2010 20:30:11 -0400 Original-Received: from [140.186.70.92] (port=48338 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXNxD-0002S3-4v for bug-gnu-emacs@gnu.org; Fri, 09 Jul 2010 20:30:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OXNxB-0008Q4-JU for bug-gnu-emacs@gnu.org; Fri, 09 Jul 2010 20:30:02 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:57350) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXNxB-0008PM-Hy for bug-gnu-emacs@gnu.org; Fri, 09 Jul 2010 20:30:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1OXNdr-0000Ju-2l; Fri, 09 Jul 2010 20:10:03 -0400 X-Loop: help-debbugs@gnu.org Resent-From: MON KEY Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 10 Jul 2010 00:10:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 6598 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.12787205831218 (code B ref -1); Sat, 10 Jul 2010 00:10:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 10 Jul 2010 00:09:43 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 Original-Received: by gwb1 with SMTP id 1so2010770gwb.0 for ; Fri, 09 Jul 2010 17:07:39 -0700 (PDT) Original-Received: by 10.150.58.20 with SMTP id g20mr2810025yba.84.1278720458984; Fri, 09 Jul 2010 17:07:38 -0700 (PDT) Original-Received: by 10.151.98.19 with HTTP; Fri, 9 Jul 2010 17:07:38 -0700 (PDT) X-Google-Sender-Auth: HlCSPrHLgKoBQEIz8mSgBvFUCHI 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Fri, 09 Jul 2010 20:10:03 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) 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: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:38329 Archived-At: 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\