Subject: bug#38792: man grep

From: Paul Eggert <[email-masked]>
Date: Sun, 29 Dec 2019 18:59:22 -0800

On 12/29/19 11:10 AM, Stephane Chazelas wrote:

> Note that that wording makes it unclear what the exit status
> should be if -o is in use.

It seems reasonably clear that a line would be selected if any part of it is
selected. Anyway, that text is exactly the same as before, so rewordsmithing it
could be a different thread.

> It should be
> 
> grep -n -- 'f.*\.c$' *g*.h /dev/null

Thanks, done in the attached patch.

> (why not using -H instead of /dev/null btw?).

I wanted the example to be portable.
>From b39fd2ad27ee5deeb9a0f7571034628c588bdda9 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Sun, 29 Dec 2019 18:57:28 -0800
Subject: [PATCH] doc: Add -- to more-complex example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Suggested by Stephane Chazelas (Bug#38792).
* doc/grep.in.1, doc/grep.texi: Add ‘--’ to recently-added example.
---
 doc/grep.in.1 | 11 ++++++++---
 doc/grep.texi |  7 ++++---
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index a382966..a91b2a6 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -1333,13 +1333,18 @@ The following example outputs the location and contents of any line
 containing \*(lqf\*(rq and ending in \*(lq.c\*(rq,
 within all files in the current directory whose names
 contain \*(lqg\*(rq and end in \*(lq.h\*(rq.
-The command also searches the empty file /dev/null,
-so that file names are displayed
+The
+.B \-n
+option outputs line numbers, the
+.B \-\-
+argument treats expansions of \*(lq*g*.h\*(rq starting with \*(lq\-\*(rq
+as file names not options,
+and the empty file /dev/null causes file names to be output
 even if only one file name happens to be of the form \*(lq*g*.h\*(rq.
 .PP
 .in +2n
 .EX
-$ \fBgrep\fP \-n 'f.*\e.c$' *g*.h /dev/null
+$ \fBgrep\fP \-n \-\- 'f.*\e.c$' *g*.h /dev/null
 argmatch.h:1:/* definitions and prototypes for argmatch.c
 .EE
 .in
diff --git a/doc/grep.texi b/doc/grep.texi
index 873b53c..42832ab 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -1585,12 +1585,13 @@ 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}.
-The command also searches the empty file @file{/dev/null},
-so that file names are displayed
+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
 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}
+$ @kbd{grep -n -- 'f.*\.c$' *g*.h /dev/null}
 argmatch.h:1:/* definitions and prototypes for argmatch.c
 @end example
 
-- 
2.17.1