Subject: bug#37604: closed (Re: bug#37604: man page description of -i confused someone)

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 03 Oct 2019 22:26:02 +0000

Your bug report

#37604: man page description of -i confused someone

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

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

Subject: Re: bug#37604: man page description of -i confused someone
From: Paul Eggert <[email-masked]>
To: Tom Limoncelli <[email-masked]>
Cc: [email-masked]
Date: Thu, 3 Oct 2019 15:25:30 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

Thanks for the bug report. I installed the attached, which should make 
things clearer, albeit a bit more tersely than you suggested.
>From 53389bc57cc30ae1454ff48245cf63a703f02024 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Thu, 3 Oct 2019 15:23:33 -0700
Subject: [PATCH] grep: tighten -i doc

* doc/grep.in.1:
* doc/grep.texi (Matching Control):
* src/grep.c (usage):
Make it clearer that -i affects patterns and data, but not
file names (Bug#37604).
---
 doc/grep.in.1 | 3 ++-
 doc/grep.texi | 3 ++-
 src/grep.c    | 2 +-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index 4a3e274..a2cbf5c 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -250,7 +250,8 @@ option, search for all patterns given.
 The empty file contains zero patterns, and therefore matches nothing.
 .TP
 .BR \-i ", " \-\^\-ignore\-case
-Ignore case distinctions, so that characters that differ only in case
+Ignore case distinctions in patterns and input data,
+so that characters that differ only in case
 match each other.
 .TP
 .BR \-v ", " \-\^\-invert\-match
diff --git a/doc/grep.texi b/doc/grep.texi
index e6e0dbe..f5edc72 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -198,7 +198,8 @@ The empty file contains zero patterns, and therefore matches nothing.
 @opindex -y
 @opindex --ignore-case
 @cindex case insensitive search
-Ignore case distinctions, so that characters that differ only in case
+Ignore case distinctions in patterns and input data,
+so that characters that differ only in case
 match each other.  Although this is straightforward when letters
 differ in case only via lowercase-uppercase pairs, the behavior is
 unspecified in other situations.  For example, uppercase ``S'' has an
diff --git a/src/grep.c b/src/grep.c
index ef6abb8..4b6b465 100644
--- a/src/grep.c
+++ b/src/grep.c
@@ -1926,7 +1926,7 @@ Pattern selection and interpretation:\n"), getprogname ());
       printf (_("\
   -e, --regexp=PATTERNS     use PATTERNS for matching\n\
   -f, --file=FILE           take PATTERNS from FILE\n\
-  -i, --ignore-case         ignore case distinctions\n\
+  -i, --ignore-case         ignore case distinctions in patterns and data\n\
   -w, --word-regexp         match only whole words\n\
   -x, --line-regexp         match only whole lines\n\
   -z, --null-data           a data line ends in 0 byte, not newline\n"));
-- 
2.21.0

Subject: man page description of -i confused someone
From: Tom Limoncelli <[email-masked]>
To: [email-masked]
Date: Thu, 3 Oct 2019 09:08:59 -0400
List-Id: <debbugs-submit.debbugs.gnu.org>

There's an interesting question about grep posted on StackOverflow.com:

       https://stackoverflow.com/questions/45717127

The user was confused why "-i" didn't apply to the NAMES of the files on
the command line.  Obviously this is a misunderstanding of the separation
of duties between the shell and the commands (shell expands wildcards, not
the command).  The top ranked answer for the question gently explained the
difference.

That said, I do take pity on the person, who may have been an early
beginner or possibly not a native English speaker.  The man page says:

       *-i*, *--ignore-case*

              Ignore case distinctions in both the PATTERN and the input

              files.

Taking off my developer hat and putting on my writer/author hat, I have to
agree that the man page could be phrased better.  I think the person got
caught up by seeing the word "files" instead of "contents". (I could also
make the case that the fact that stdin isn't really a file means the
sentence is inaccurate.)

My suggestion is to change the description to be:

   Ignore case distinctions in both the PATTERN and the contents being
searched.

even better would be to break it into multiple sentences. This would make
it perfectly clear:

   Ignore case during the search. Case is ignored in both the input
contents PATTERN and the contents being searched.

Tom

-- 
Email: [email-masked]    Work: [email-masked]
Blog:  http://EverythingSysadmin.com/