GNU bug report logs - #6598
Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement.

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Severity: minor; Reported by: MON KEY <monkey@HIDDEN>; dated Sat, 10 Jul 2010 00:10:02 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 10 Jul 2010 00:09:43 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Jul 09 20:09:43 2010
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1OXNdX-0000Jb-51
	for submit <at> 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 <stan@HIDDEN>) id 1OXNdV-0000JW-9m
	for submit <at> 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 <stan@HIDDEN>) id 1OXNdR-00031T-Cf
	for submit <at> 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@HIDDEN; 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 <stan@HIDDEN>) id 1OXNbZ-0005ht-5S
	for bug-gnu-emacs@HIDDEN; 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 <stan@HIDDEN>) id 1OXNbZ-0005hj-1m
	for bug-gnu-emacs@HIDDEN; Fri, 09 Jul 2010 20:07:41 -0400
Received: by gwb1 with SMTP id 1so2010770gwb.0
	for <bug-gnu-emacs@HIDDEN>; 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: <AANLkTilQ6O1r4H9mqobLfUsdvX7nAO_Oux82NcdYht-T@HIDDEN>
Subject: Documentation: progmodes/grep.el -- numerous errors ommissions and 
	opportunities for improvement.
From: MON KEY <monkey@HIDDEN>
To: bug-gnu-emacs@HIDDEN
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 <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/pipermail/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> 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 <C>, <D>, <F>, <R>, and <X>."

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":

 <C>, <F>, <X>, <R>, <N>

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\




Acknowledgement sent to MON KEY <monkey@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to owner <at> debbugs.gnu.org, bug-gnu-emacs@HIDDEN:
bug#6598; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Fri, 31 Oct 2014 17:00:04 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.