Subject: Re: bug#48948: grep documentation feedback

From: Paul Eggert <[email-masked]>
Date: Thu, 10 Jun 2021 16:10:35 -0700

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