Subject: bug#65046: closed (Re: bug#65046: Error in the "grep" documentation, section "2.1.7 Other Options": "--")

From: [email-masked] (GNU bug Tracking System)
Date: Sun, 06 Aug 2023 01:56:02 +0000

Your bug report

#65046: Error in the "grep" documentation, section "2.1.7 Other Options": "--"

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].

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

Subject: Re: bug#65046: Error in the "grep" documentation, section "2.1.7 Other Options": "--"
From: Paul Eggert <[email-masked]>
To: "Helmut Waitzmann Anti-Spam-Ticket.b.qc3c" <[email-masked]>
Cc: [email-masked]
Date: Sat, 5 Aug 2023 18:54:54 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

Thanks for reporting that. I installed the attached patch.

From 13fd8279e5fdd15ba711cf6e5eadeece89e85909 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Sat, 5 Aug 2023 14:58:09 -0700
Subject: [PATCH] doc: clarify -- role

This should fix bug#65046 reported by Helmut Waltzmann.
---
 doc/grep.in.1 |  4 ++--
 doc/grep.texi | 10 +++++-----
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index 236791e..01f753a 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -1299,7 +1299,7 @@ contain \*(lqg\*(rq and end in \*(lq.h\*(rq.
 The
 .B \-n
 option outputs line numbers, the
-.B \-\-
+.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
@@ -1307,7 +1307,7 @@ 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 594ac1f..42b499a 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -555,7 +555,7 @@ Print @var{num} lines of leading and trailing output context.
 @opindex --group-separator
 @cindex group separator
 When @option{-A}, @option{-B} or @option{-C} are in use,
-print @var{string} instead of @option{--} between groups of lines.
+print @var{string} instead of @samp{--} between groups of lines.
 
 @item --no-group-separator
 @opindex --group-separator
@@ -770,10 +770,10 @@ directory, recursively, following all symbolic links.
 @item --
 @opindex --
 @cindex option delimiter
-Delimit the option list.  Later arguments, if any, are treated as
-operands even if they begin with @samp{-}.  For example, @samp{grep PAT --
--file1 file2} searches for the pattern PAT in the files named @file{-file1}
-and @file{file2}.
+Delimit the option list.  Any later argument is not treated as an
+option even if it begins with @samp{-}.  For example,
+@samp{grep -- -PAT -file1 file2} searches for the pattern @samp{-PAT}
+in the files named @file{-file1} and @file{file2}.
 
 @item --line-buffered
 @opindex --line-buffered
-- 
2.39.2

Subject: Error in the "grep" documentation, section "2.1.7 Other Options": "--"
From: Helmut Waitzmann <[email-masked]>
To: GNU grep bug reporting team <[email-masked]>
Date: Thu, 03 Aug 2023 21:57:23 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

Hello, GNU grep bug reporting team,

in the section "2.1.7 Other Options" of the "grep" "info"
documentation (for example in
<https://www.gnu.org/software/grep/manual/html_node/Other-Options.html>),
the hint about the usage of the "--" option delimiter is wrong: 
It won't work, if the pattern "PAT" happens to start with a "-". 
And if the environment variable "POSIXLY_CORRECT" is set, it
won't even work with any pattern (except the pattern "--").

The following example may show it:

How to reproduce:  In an empty directory, run the following
commands:

  printf '%s\n' -1 +1 > -file1 &&
  printf '%s\n' -2 +2 > file2 &&
  grep '-[[:digit:]]' -- -file1 file2

Received output:

  grep: invalid option -- '['
  Usage: grep [OPTION]... PATTERN [FILE]...
  Try `grep --help' for more information.

Expected output:  According to the manual, the output should be

  -file1:-1
  file2:-2

=> The hint in the documentation is wrong:  Rather than

  ‘--’
       Delimit the option list.  Later arguments, if any, are
       treated as operands even if they begin with ‘-’.  For
-      example, ‘grep PAT -- -file1 file2’ searches for the
       pattern PAT in the files named ‘-file1’ and ‘file2’.

it should say:

  ‘--’
       Delimit the option list.  Later arguments, if any, are
       treated as operands even if they begin with ‘-’.  For
+      example, ‘grep -- PAT -file1 file2’ searches for the
       pattern PAT in the files named ‘-file1’ and ‘file2’.

(the differing lines are marked in the first position with "-"
resp. "+").

Working example:

  printf '%s\n' -1 +1 > -file1 &&
  printf '%s\n' -2 +2 > file2 &&
  grep -- '-[[:digit:]]' -file1 file2

Received output:

  -file1:-1
  file2:-2

Explanation:  As the pattern PAT shall be the first non-option
argument given to "grep", the option list delimiter "--", when
placed before the pattern in "grep"s invocation arguments list,
prevents the pattern from being misinterpreted as an option
(regardless of the POSIXLY_CORRECT environment variable being set
or unset).

Kind regards

Helmut Waitzmann