Subject: bug#48948: closed (Re: bug#48948: grep documentation feedback)

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 10 Jun 2021 23:11:02 +0000

Your bug report

#48948: grep documentation feedback

which was filed against the grep package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
48948: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=48948
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#48948: grep documentation feedback
From: Paul Eggert <[email-masked]>
To: David Apps <[email-masked]>
Cc: [email-masked]
Date: Thu, 10 Jun 2021 16:10:35 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

On 6/10/21 12:42 PM, David Apps via Bug reports for GNU grep wrote:

> Perhaps changing "of word" to "of a word"

Good idea, thanks.

> In basic regular expressions the meta-characters ?, +, {, |, (, and ) 
> lose their special meaning; instead use the backslashed versions \?, \+, 
> \{, \|, \(, and \).
> 
> Should } and \} appear in these lists?

No, as '}' is not a meta-character in EREs. The '}' case is different 
and this is discussed in the next sentence.

> 3. In the section "4 Usage":
> 
> $ grep -n -- 'f.*\.c$' *g*.h /dev/null
> 
> The other examples do not begin with $. Perhaps remove $ for greater 
> consistency.

That's easy enough. Also, I noticed that the surrounding explanation is 
a bit wrong, so I fixed that too.

> 4. In the section "4 Usage", perhaps the answer to question 3 would be 
> better if the examples used -* in place of * to search for files that 
> begin with -.

The problem almost always occurs with patterns that begin with "*" and 
unexpectedly match file names beginning with "-", so in some sense it's 
better to leave this example as-is so that it's more-typical.

I installed the attached patch to implement the above. Thanks for your 
feedback.
From e6571dfd459f55de975ef457cf7dbd4b49ec491c Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Thu, 10 Jun 2021 14:55:21 -0700
Subject: [PATCH] doc: improve examples and wording

* doc/grep.texi (The Backslash Character and Special Expressions)
(Usage): Improve doc (Bug#48948).
---
 doc/grep.texi | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/doc/grep.texi b/doc/grep.texi
index e3b1555..01ac81e 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -1479,10 +1479,10 @@ Match the empty string at the edge of a word.
 Match the empty string provided it's not at the edge of a word.
 
 @item \<
-Match the empty string at the beginning of word.
+Match the empty string at the beginning of a word.
 
 @item \>
-Match the empty string at the end of word.
+Match the empty string at the end of a word.
 
 @item \w
 Match word constituent, it is a synonym for @samp{[_[:alnum:]]}.
@@ -1667,23 +1667,22 @@ The @option{-i} option causes @command{grep}
 to ignore case, causing it to match the line @samp{Hello, world!}, which
 it would not otherwise match.
 
-Here is a more complex example session,
+Here is a more complex example,
 showing the location and contents of any line
 containing @samp{f} and ending in @samp{.c},
 within all files in the current directory whose names
-contain @samp{g} and end in @samp{.h}.
+start with non-@samp{.}, contain @samp{g}, and end in @samp{.h}.
 The @option{-n} option outputs line numbers, the @option{--} argument
-treats any later arguments starting with @samp{-} as file names not
-options, and the empty file @file{/dev/null} causes file names to be output
+treats any later arguments as file names not options even if
+@code{*g*.h} expands to a file name that starts with @samp{-},
+and the empty file @file{/dev/null} causes file names to be output
 even if only one file name happens to be of the form @samp{*g*.h}.
 
 @example
-$ @kbd{grep -n -- 'f.*\.c$' *g*.h /dev/null}
-argmatch.h:1:/* definitions and prototypes for argmatch.c
+grep -n -- 'f.*\.c$' *g*.h /dev/null
 @end example
 
 @noindent
-The only line that contains a match is line 1 of @file{argmatch.h}.
 Note that the regular expression syntax used in the pattern differs
 from the globbing syntax that the shell uses to match file names.
 
-- 
2.30.2

Subject: grep documentation feedback
From: David Apps <[email-masked]>
To: [email-masked]
Date: Thu, 10 Jun 2021 20:42:03 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

I hope that you are well.

Thank you for your work on this great software.

I have some feedback about the document at the following address:

http://www.gnu.org/software/grep/manual/grep.html

When quoting from this document, I have removed the non-ASCII 
characters. The characters that I have removed were left and right 
single quotation marks.

1. In the section "3.3 The Backslash Character and Special Expressions":

\<
Match the empty string at the beginning of word.
\>
Match the empty string at the end of word.

Perhaps changing "of word" to "of a word" would be more consistent with 
the language elsewhere in the document.

2. In the section "3.6 Basic vs Extended Regular Expressions":

In basic regular expressions the meta-characters ?, +, {, |, (, and ) 
lose their special meaning; instead use the backslashed versions \?, \+, 
\{, \|, \(, and \).

Should } and \} appear in these lists?

3. In the section "4 Usage":

$ grep -n -- 'f.*\.c$' *g*.h /dev/null

The other examples do not begin with $. Perhaps remove $ for greater 
consistency.

4. In the section "4 Usage", perhaps the answer to question 3 would be 
better if the examples used -* in place of * to search for files that 
begin with -.

Thank you.

David