GNU bug report logs - #37604
man page description of -i confused someone

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 37604 in the body.
You can then email your comments to 37604 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Tom Limoncelli <tal <at> whatexit.org>
To: bug-grep <at> gnu.org
Subject: man page description of -i confused someone
Date: Thu, 3 Oct 2019 09:08:59 -0400

[Message part 1 (text/plain, inline)]

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: tal <at> whatexit.org    Work: tlimoncelli <at> StackOverflow.com
Blog:  http://EverythingSysadmin.com/

[Message part 2 (text/html, inline)]

Message #10 received at 37604-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Tom Limoncelli <tal <at> whatexit.org>
Cc: 37604-done <at> debbugs.gnu.org
Subject: Re: bug#37604: man page description of -i confused someone
Date: Thu, 3 Oct 2019 15:25:30 -0700

[Message part 1 (text/plain, inline)]

Thanks for the bug report. I installed the attached, which should make 
things clearer, albeit a bit more tersely than you suggested.

[0001-grep-tighten-i-doc.patch (text/x-patch, attachment)]

Message #13 received at 37604-done <at> debbugs.gnu.org (full text, mbox):

From: Tom Limoncelli <tal <at> whatexit.org>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 37604-done <at> debbugs.gnu.org
Subject: Re: bug#37604: man page description of -i confused someone
Date: Thu, 3 Oct 2019 19:13:27 -0400

[Message part 1 (text/plain, inline)]

Thanks!

On Thu, Oct 3, 2019 at 6:25 PM Paul Eggert <eggert <at> cs.ucla.edu> wrote:

> Thanks for the bug report. I installed the attached, which should make
> things clearer, albeit a bit more tersely than you suggested.
>


-- 
Email: tal <at> whatexit.org    Work: tlimoncelli <at> StackOverflow.com
Blog:  http://EverythingSysadmin.com/

[Message part 2 (text/html, inline)]

Message #16 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stephane Chazelas <stephane.chazelas <at> gmail.com>
To: bug-grep <at> gnu.org
Subject: Re: bug#37604: man page description of -i confused someone
Date: Fri, 4 Oct 2019 10:14:47 +0100

2019-10-03 09:08:59 -0400, Tom Limoncelli:
[...]
>        *-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.)
[...]


While it's obvious when you know how shell glob expansion works that

grep -ie pattern -- *.txt

won't match pattern against the contents of foo.TXT (unless you
enable the "nocaseglob" option of some shells), it's less clear
in

grep -i -r --include='*.txt' pattern .

I would have just written:

    Ignore case distinctions in the PATTERN and the input

-- 
Stephane

Message #19 received at 37604 <at> debbugs.gnu.org (full text, mbox):

From: Tom Limoncelli <tal <at> whatexit.org>
To: Stephane Chazelas <stephane.chazelas <at> gmail.com>
Cc: 37604 <at> debbugs.gnu.org
Subject: Re: bug#37604: man page description of -i confused someone
Date: Fri, 4 Oct 2019 09:33:48 -0400

On Fri, Oct 4, 2019 at 5:31 AM Stephane Chazelas
<stephane.chazelas <at> gmail.com> wrote:
>
>
> I would have just written:
>
>     Ignore case distinctions in the PATTERN and the input

I like that phrasing the best!

-- 
Email: tal <at> whatexit.org    Work: tlimoncelli <at> StackOverflow.com
Blog:  http://EverythingSysadmin.com/

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.