GNU logs - #6598, boring messages


Message sent to owner <at> debbugs.gnu.org, bug-gnu-emacs@HIDDEN:


X-Loop: help-debbugs@HIDDEN
Subject: bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions and  opportunities for improvement.
Resent-From: MON KEY <monkey@HIDDEN>
Original-Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Resent-To: owner <at> debbugs.gnu.org
Resent-CC: bug-gnu-emacs@HIDDEN
Resent-Date: Sat, 10 Jul 2010 00:10:02 +0000
Resent-Message-ID: <handler.6598.B.12787205831218 <at> debbugs.gnu.org>
Resent-Sender: help-debbugs@HIDDEN
X-GNU-PR-Message: report 6598
X-GNU-PR-Package: emacs
X-GNU-PR-Keywords: 
To: 6598 <at> debbugs.gnu.org
X-Debbugs-Original-To: bug-gnu-emacs@HIDDEN
Received: via spool by submit <at> debbugs.gnu.org id=B.12787205831218
          (code B ref -1); Sat, 10 Jul 2010 00:10:02 +0000
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 <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>
From: MON KEY <monkey@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-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\




Message sent:


Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-Mailer: MIME-tools 5.427 (Entity 5.427)
Content-Type: text/plain; charset=utf-8
X-Loop: help-debbugs@HIDDEN
From: help-debbugs@HIDDEN (GNU bug Tracking System)
To: MON KEY <monkey@HIDDEN>
Subject: bug#6598: Acknowledgement (Documentation: progmodes/grep.el --
 numerous errors ommissions and  opportunities for improvement.)
Message-ID: <handler.6598.B.12787205831218.ack <at> debbugs.gnu.org>
References: <AANLkTilQ6O1r4H9mqobLfUsdvX7nAO_Oux82NcdYht-T@HIDDEN>
X-Gnu-PR-Message: ack 6598
X-Gnu-PR-Package: emacs
Reply-To: 6598 <at> debbugs.gnu.org
Date: Sat, 10 Jul 2010 00:10:03 +0000

Thank you for filing a new bug report with GNU.

This is an automatically generated reply to let you know your message
has been received.

Your message is being forwarded to the package maintainers and other
interested parties for their attention; they will reply in due course.

Your message has been sent to the package maintainer(s):
 bug-gnu-emacs@HIDDEN

If you wish to submit further information on this problem, please
send it to 6598 <at> debbugs.gnu.org.

Please do not send mail to help-debbugs@HIDDEN unless you wish
to report a problem with the Bug-tracking system.

--=20
6598: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D6598
GNU Bug Tracking System
Contact help-debbugs@HIDDEN with problems



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.