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

[Helmut Waitzmann]

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

pgp122AM6ezuo.pgp
Description: PGP signature